Generate ROS Custom Messages in MATLAB

Use custom messages to extend the set of message types currently supported in ROS. Custom messages are messages that you define. 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.