ros2genmsg

Generate custom messages from ROS 2 definitions

Description

example

ros2genmsg(folderpath) generates MATLAB® interfaces to ROS 2 custom messages. Specify the path to a folder that contains the definitions of the custom messages as .msg files.

You must have the following installed on your system:

  • Python 3.7+

  • CMake 3.10+

  • C++ compiler to match the build environment

    • Visual Studio 2017

    • Xcode 10.x

    • GCC 6.3.x

Examples

collapse all

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.

To use ROS 2 custom messages, you must have the following installed on your computer:

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_interfaces 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 msg file.

After ensuring that your custom message package is correct, note the folder path location.Then, call ros2genmsg with the specified path. The following example provided three messages example_package_a, example_package_b, and 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_interfaces");
copyfile("example_*_msgs",folderPath);

Specify the folder path for custom message files and call ros2genmsg to create custom messages for MATLAB.

ros2genmsg(folderPath)
Identifying message files in folder '//fs-58-ah/vmgr$/home08/agadkari/Documents/MATLAB/Examples/ros-ex44405863/custom_interfaces'.Done.
Validating message files in folder '//fs-58-ah/vmgr$/home08/agadkari/Documents/MATLAB/Examples/ros-ex44405863/custom_interfaces'.Done.
Generating MATLAB interfaces.Done.
Running colcon build in folder '//fs-58-ah/vmgr$/home08/agadkari/Documents/MATLAB/Examples/ros-ex44405863/custom_interfaces/matlab_msg_gen/win64'.Done.
build log

Call 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 example_package_b/Standalone message.

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

Use LatestMessage field to know the recent message recieved by the subscriber.

sub.LatestMessage
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

Input Arguments

collapse all

Path to folder of ROS message packages, specified as a string scalar or character vector. Each package folder should contain a /msg folder with .msg files for message definitions. For more information, see About ROS 2 Interfaces.

Example: "/ros_package/msg/"

Data Types: char | string

Limitations

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.

MATLAB Compiler

  • ROS 2 custom messages and the ros2genmsg function are not supported with MATLAB Compiler™.

Introduced in R2019b