Generate custom messages from ROS 2 definitions
ros2genmsg( generates ROS 2
custom messages in MATLAB® by reading ROS 2 custom messages and service definitions in the specified
folder path. The function expects one or more ROS 2 package folders inside the folder
path. These packages contain the message definitions in
.msg files and
the service definitions in
After calling this function, you can send and receive your custom messages in
MATLAB like all other supported messages. You can create these messages using
view the list of messages by calling
ros2 msg list.
When generating custom messages for ROS 2, you must build the ROS 2 packages. This requires you to have CMake and a C++ compiler for your platform. For more information, see ROS System Requirements
The custom messages from the ROS 2 definitions have to be regenerated for every new release.
The Custom messages generated by MATLAB now supports both eProsima Fast DDS and Eclipse Cyclone DDS middleware. For more information on ROS middleware implementations see Switching Between ROS Middleware Implementations.
ROS 2 Custom Message Support
Custom messages are user-defined messages that you can use to extend the set of message types currently supported in ROS 2. 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
ros2 msg list in the MATLAB® Command Window. For more information about supported ROS 2 messages, see Work with Basic ROS 2 Messages.
If this if your first time working with ROS 2 custom messages, check the ROS System Requirements.
Custom messages Contents
ROS 2 custom messages are specified in ROS 2 package folders that contain a
msg directory. The
msg folder contains all your custom message type definitions. For example, the package
example_b_msgs, within the
custom folder, has the below folder and file structure.
The package contains one custom message type,
Standalone.msg. MATLAB uses these files to generate the necessary files for using the custom messages contained in the package. For more information on message naming conventions, see ROS 2 Interface Definition.
In this example, you go through the procedure for creating ROS 2 custom messages in MATLAB®. You must have a ROS 2 package that contains the required
After ensuring that your custom message package is correct, note the folder path location, and then, call
ros2genmsg with the specified path. The following example provided three messages
example_package_c that have dependencies. This example also illustrates that you can use a folder containing multiple messages and generate them all at the same time.
To set up custom messages in MATLAB, open MATLAB in a new session. Place your custom message folder in a location and note the folder path. In this example, the custom message interface folder is present in the current directory. If you are creating custom message packages in a separate location, provide the appropriate path to the folder that contains the custom message packages.
folderPath = fullfile(pwd,"custom"); copyfile("example_*_msgs",folderPath);
Specify the folder path for custom message files and call
ros2genmsg to create custom messages for MATLAB.
Identifying message files in folder 'U:/Documents/MATLAB/Examples/ros-ex44405863/custom'.Done. Validating message files in folder 'U:/Documents/MATLAB/Examples/ros-ex44405863/custom'.Done. [3/3] Generating MATLAB interfaces for custom message packages... Done. Running colcon build in folder 'U:/Documents/MATLAB/Examples/ros-ex44405863/custom/matlab_msg_gen/win64'. Build in progress. This may take several minutes... Build succeeded.build log
ros2 msg list to verify creation of new custom messages.
You can now use the above created custom message as the standard messages. For more information on sending and receiving messages, see Exchange Data with ROS 2 Publishers and Subscribers.
Create a publisher to use
node = ros2node("/node_1"); pub = ros2publisher(node,"/example_topic","example_b_msgs/Standalone");
Create a subscriber on the same topic.
sub = ros2subscriber(node,"/example_topic");
Create a message and send the message.
custom_msg = ros2message("example_b_msgs/Standalone"); custom_msg.int_property = uint32(12); custom_msg.string_property='This is ROS 2 custom message example'; send(pub,custom_msg); pause(3) % Allow a few seconds for the message to arrive
LatestMessage field to know the recent message received by the subscriber.
ans = struct with fields: int_property: 12 string_property: 'This is ROS 2 custom message example'
Remove the created ROS objects.
clear node pub sub
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.
folderpath — Path to ROS interfaces folder
string scalar | character vector
Path to the ROS interfaces folder, which is the parent folder of ROS message
packages, specified as a string scalar or character vector. The parent folder should
package.xml file and package folders. These folders contain
/msg folder with
.msg files for message
definitions and a
/srv folder with
.srv files for
service definitions. For more information, see About ROS 2
Specify optional pairs of arguments as
the argument name and
Value is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name in quotes.
BuildConfiguration — Build configuration
'fasterbuilds' (default) |
Build configuration, specified as the comma-separated pair consisting of
'BuildConfiguration' and a character vector or string scalar
'fasterbuilds'— Build the message libraries with compiler optimizations for shorter build times.
'fasterruns'— Build the message libraries with compiler optimizations for faster execution.
After generating custom messages, restart any existing ROS 2 nodes.
Code Generation with custom messages:
Custom message and service types can be used with ROS 2 functionality for generating C++ code for a standalone ROS 2 node. The generated code (.tgz archive) will include definitions for the custom messages, but it will not include the ROS 2 custom message packages. When the generated code is built in the destination, it expects the custom message packages to be available in the colcon workspace which should be your current working directory. Please ensure that you either install or copy the custom message package to your system before building the generated code.
ROS 2 custom messages and the
ros2genmsgfunction are not supported with MATLAB Compiler™.