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
list in the MATLAB® Command Window.
To install custom message support, call
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.
ROS custom messages are specified in ROS package folders that contain a
package.xml file and optional
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
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
package.xml file, which has the
Other dependencies on message packages (optional) —
Here is a sample
package.xml file with the previously shown
<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
sensor_msgs/Image message has these fields in
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
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
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.
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).
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
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,
_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
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
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.