ROS 2 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
list in the MATLAB® Command Window.
Custom message creation requires ROS 2 packages, which are detailed in the ROS Wiki at ROS 2 Packages. After ensuring that you have valid ROS 2 packages for custom
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 2
custom message in MATLAB, see Create Shareable ROS 2 Custom Message Package.
If this is your first time using ROS 2 custom messages, check ROS Toolbox System Requirements.
Custom Message Contents
ROS 2 custom messages are specified in ROS package folders that contains
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.
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
matlab_msg_gen has this folder and file structure.
The package contains one custom message type in
Num.msg and one
custom service type in
AddTwoInts.srv, and one custom action type in
Test.action. 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 ROS 2 msg and srv on ROS 2 documentation.
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
with your known path to the custom message files to create MATLAB code.
function takes your custom message files (
.action) and converts each message
type to working MATLAB code. The
ros2genmsg 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 functions that define the message properties when you create new custom
messages. The function then creates the required MATLAB M-files for the different
function creates these files, you must add the function files to the MATLAB path. These steps are given as prompts in the MATLAB Command Window. Use
function to verify that the new custom messages are available.
For an example of this procedure, see Create Shareable ROS 2 Custom Message 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 2 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
colcon workspace or on the
Ensure that you either install or copy the custom message package to your Linux
system before building the generated code.
Replacing Definitions of Built-In Messages With Custom Definitions
MATLAB provides a lot of built-in ROS 2 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.