Main Content

rosgenmsg

Generate custom messages from ROS definitions

collapse all in page

Syntax

rosgenmsg(folderpath)
rosgenmsg(folderpath,Name=Value)

Description

rosgenmsg(folderpath) generates ROS custom messages by reading ROS custom messages, service definitions, and action definitions in the specified folder path. The function folder must contain one or more ROS package folders. These packages contain the message definitions in .msg files, service definitions in .srv files, and action definitions in .action files.

After you generate the custom messages, you can send and receive them in MATLAB® like all the other supported messages. You can create these messages using rosmessage or view the list of messages by entering rosmsg list at the MATLAB Command Window.

Note

  • To generate custom messages for ROS, you must build the ROS packages. This process requires you to have access to CMake software and a C++ compiler for your platform. For more information, see ROS Toolbox System Requirements

  • With every new release of MATLAB, you must regenerate the custom messages from the ROS definitions.

example

rosgenmsg(folderpath,Name=Value) specifies additional options using one or more name-value arguments.

Examples

collapse all

Open Live Script

Custom messages are messages that you define. Use custom messages to extend the set of message types currently supported in ROS. If you are sending and receiving supported message types, you do not need to use custom messages. To see the list of supported message types, enter rosmsg list in the MATLAB Command Window. For more information about supported ROS messages, see Work with Basic ROS Messages.

If this is your first time working with ROS custom messages, see ROS Toolbox System Requirements.

ROS custom messages are specified in ROS package folders that contain a folder named msg. The msg folder contains all your custom message type definitions. For example, the simple_msgs package in the rosCustomMessages folder, has this folder and file structure.

The package contains the custom message type Num.msg. MATLAB uses these files to generate the necessary files for using the custom messages contained in the package.

In this example, you create ROS custom messages in MATLAB and compress them in a shareable ZIP archive. You must have a ROS package that contains the required msg file.

After you prepare your custom message package folder, you specify the path to the parent folder and call rosgenmsg with the specified path.

Open a new MATLAB session and create a custom message package folder in a local folder. Choose a short folder path when you generate custom messages on a Windows machine to avoid limitations on the number of characters in the folder path. For example,

genDir = fullfile('C:/test/rosCustomMessages')

genDir = fullfile(pwd,'rosCustomMessages');
packagePath = fullfile(genDir,'simple_msgs');
mkdir(packagePath)

Create a folder named msg inside the custom message package folder.

mkdir(packagePath,'msg')

Create a file named .msg inside the msg folder.

messageDefinition = {'int64 num'};

fileID = fopen(fullfile(packagePath,'msg', ...
               'Num.msg'),'w');
fprintf(fileID,'%s\n',messageDefinition{:});
fclose(fileID);

Create a folder named srv inside the custom message package folder.

mkdir(packagePath,'srv')

Create a file named .srv inside the srv folder.

serviceDefinition = {'int64 a'
                     'int64 b'
                     '---'
                     'int64 sum'};
 
fileID = fopen(fullfile(packagePath,'srv', ...
               'AddTwoInts.srv'),'w');
fprintf(fileID,'%s\n',serviceDefinition{:});
fclose(fileID);

Create a folder named action inside the custom message package folder.

mkdir(packagePath,'action')

Create a file named .action inside the action folder.

actionDefinition = {'int64 goal'
                    '---'
                    'int64 result'
                    '---'
                    'int64 feedback'};
 
fileID = fopen(fullfile(packagePath,'action', ...
               'Test.action'),'w');
fprintf(fileID,'%s\n',actionDefinition{:});
fclose(fileID);

Generate custom messages from ROS definitions in .msg, .srv, and .action files. Use the CreateShareableFile name-value argument to create a shareable ZIP archive of the generated custom messages.

For information about how to use use this ZIP archive to register the custom messages in another machine, see rosRegisterMessages.

rosgenmsg(genDir,CreateShareableFile=true)
Identifying message files in folder 'C:/test/rosCustomMessages'.Done.
Creating a Python virtual environment.Done.
Adding required Python packages to virtual environment.Done.
Copying include folders.Done.
Copying libraries.Done.
Validating message files in folder 'C:/test/rosCustomMessages'.Done.
[1/1] Generating MATLAB interfaces for custom message packages... Done.
Running catkin build in folder 'C:/test/rosCustomMessages/matlab_msg_gen_ros1/win64'.
Build in progress. This may take several minutes...
Build succeeded.build log
Generating zip file in the folder 'C:/test/rosCustomMessages'.Done.
 
To use the custom messages, follow these steps:
 
1. Add the custom message folder to the MATLAB path by executing:
 
addpath('C:\test\rosCustomMessages\matlab_msg_gen_ros1\win64\install\m')
savepath
 
2. Refresh all message class definitions, which requires clearing the workspace, by executing:
 
clear classes
rehash toolboxcache
 
3. Verify that you can use the custom messages. 
   Enter "rosmsg list" and ensure that the output contains the generated
   custom message types.

Verify creation of the new custom messages by entering rosmsg list.

Input Arguments

collapse all

Path to the ROS message packages, specified as a string scalar or character vector. The parent folder must contain package folders. These folders contain a folder named /msg with .msg files for message definitions, a folder named /srv with .srv files for service definitions, and a folder named /action with .action files for action definitions.

Example: 'C:/test/rosCustomMessages'

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is 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.

Example: BuildConfiguration='fasterruns'

Build configuration, specified as one of these values.

  • 'fasterbuilds' — Build the message libraries with compiler optimizations for shorter build times. This is the default configuration.

  • 'fasterruns' — Build the message libraries with compiler optimizations for faster execution.

Example: rosgenmsg('C:/test/rosCustomMessages',BuildConfiguration='fasterruns')

Data Types: char | string

Option to create a sharable ZIP archive, specified as a numeric or logical 1 (true) or 0 (false).

When you specify this argument as 1 (true), the function creates a ZIP archive be compressing the install folder in the matlab_msg_gen_ros1 folder. You can use this file with another machine running on the same platform and using the same MATLAB version.

When you specify this argument as 0 (false), the function does not create a ZIP archive.

Example: rosgenmsg('C:/test/rosCustomMessages',CreateShareableFile=true)

Data Types: logical

Limitations

MATLAB Compiler™ software do not support ROS custom messages and the rosgenmsg function.

Version History

Introduced in R2019b

See Also

|

Topics

External Websites