Custom messages are user-defined messages that you can use to
extend the set of message types currently supported in Robotics System
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,
rosmsg list in the MATLAB® Command Window.
To install custom message support, call
roboticsAddons and follow the instructions for installation. 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 to generate the necessary MATLAB code to use custom messages. For an example on how to generate a ROS
custom message in MATLAB, seeCreate Custom Messages from ROS Package.
ROS custom messages are specified in ROS package folders that
package.xml file and optional
msg folder contains all your custom message
type definitions. You should also add all custom service type definitions
srv folder. For example, the package
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
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
In all packages, you must define a
which has the following contents:
Other dependencies on message packages (optional)
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>
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
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
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.
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
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 (
and converts each message type to working MATLAB code. The
will look for
.msg files in the
.srv files in the
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
and then creates MATLAB program for each topic and service. Do
not modify the
.jar files because MATLAB uses
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
Add the specified paths as new lines of text in the
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).
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 Robotics System 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
as the prompt directs. Do not modify the path. This file is used to
load Java files at the start of each MATLAB session.
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
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
path to the
javaclasspath.txt file and the
to the MATLAB path. After restarting MATLAB, other users
can use the custom messages like any other ROS message.
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
Please ensure that you either install or copy the custom message package
to your Linux system before building the generated code.