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.

To install custom message support, call rosAddons and follow the instructions in for installation in ROS Toolbox Interface for ROS Custom Messages. 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 your custom message package 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.

Custom Message Contents

ROS custom messages are specified in ROS package folders that contain a package.xml file and optional msg and srv directories. The msg folder contains all your custom message type definitions. You should also add all custom service type definitions to the srv 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. 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.

In all packages, you must define a package.xml file, which has the following contents:

Name — custom_robot_msgs
Version — 1.1.01
Dependency — message_generation
Other dependencies on message packages (optional) — geometry_msgs, std_msgs

Here is a sample package.xml file with the previously shown contents.

<package>
	<name>custom_robot_msgs</name>
	<version>1.1.01</version>
	
	<build_depend>message_generation</build_depend>
	<build_depend>geometry_msgs</build_depend>
	<build_depend>std_msgs</build_depend>
</package>

Note

You must have write access to the custom messages folder.
At any time, there should only be one custom messages folder on the MATLAB path. This folder can contain multiple packages, but it is recommended that you keep them all in one unique folder.
ROS actions are not currently supported and will be ignored during the custom message generation.
ROS packages will not be processed if both of these conditions are met:
- A package with the same name already exists
- The version number of that existing package is the same

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.

Then, the two main creation steps that are handled by the rosgenmsg function. This function takes your custom message files (.msg, .srv and package.xml) and converts each message type to working MATLAB code. The rosgenmsg function will look for .msg files in the msg folder and for .srv files in the srv folder. This code is a group of classes that define the message properties when you create new custom messages. The basic procedure takes the custom message files and converts them to .jar files and then creates MATLAB program for each topic and service. Do not modify the .jar files because MATLAB uses them internally.

After the rosgenmsg function creates these files, you must add the files to the Java class path and the MATLAB path before you can use the custom messages. These steps are given as prompts in the MATLAB Command Window:

Add location of files to javaclasspath.txt: Add the specified paths as new lines of text in the javaclasspath.txt file. If this file does not exist, a message in the command window prompts you to create it. This text file defines the static class path for Java classes. For more information on the Java class path, see Java Class Path (MATLAB).
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.
Restart MATLAB and verify messages are available: After restarting MATLAB, call rosmsg list or rosmessage to check that you can use the messages as expected.

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 Java class path and MATLAB path that contain the files directories. Make sure that the MATLAB path has only one folder at a time that contains custom message artifacts. Also, ensure you add the correct paths to the javaclasspath.txt, as the prompt directs. Do not modify the path. This file is used to load Java files at the start of each MATLAB session.

Sharing Custom Messages

After creating your custom message files, you can share them with other users. Other people do not need to call rosgenmsg to access your messages. Instead, to share your messages, access the _matlab_gen folder and follow the same three steps for specifying paths as described previously. If you have access to these files, either over a network or shared drive, add the matlab_gen/jar folder path to the javaclasspath.txt file and the matlab_gen/msggen path to the MATLAB path. After restarting MATLAB, other users can use the custom messages like any other ROS message.

Code Generation with Custom messages

Custom message and service types can be used with ROS Simulink blocks for generating C++ code for a standalone ROS node. The generated code (.tgz archive) will include Simulink definitions for the custom messages, but it will not include the ROS custom message packages. When the generated code is built in the destination Linux System, it expects the custom message packages to be available in the catkin workspace or on the ROS_PACKAGE_PATH. Please ensure that you either install or copy the custom message package to your Linux system before building the generated code.

Documentation