Main Content

ros2RegisterMessages

Register ROS 2 custom messages with MATLAB

Since R2022b

    Description

    ros2RegisterMessages(genDir) registers the custom messages with MATLAB®. Use this function to register the custom messages generated on another computer running on the same platform and same version of MATLAB.

    Note

    The ros2RegisterMessages function allows sharing of the custom messages on different machines running on the same platform only. Use the ros2genmsg function on the new platform if the machines are running on different platforms.

    example

    Examples

    collapse all

    In this example, you create ROS 2 custom messages in MATLAB® to share them on another machine. This other machine must run on the same platform and same version of MATLAB®. You must have a ROS 2 package that contains the required msg file, as this figure shows.

    ROS 2 Custom

    Open a new MATLAB session and create a custom message package folder in a local folder. Specify 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:/Work/ros2CustomMessages').

    genDir = fullfile(pwd,'ros2CustomMessages');
    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 the custom messages from the ROS 2 definitions in .msg, .srv and .action files as a shareable ZIP archive.

    ros2genmsg(genDir,CreateShareableFile=true)
    Identifying message files in folder 'C:/Work/ros2CustomMessages'.Done.
    Validating message files in folder 'C:/Work/ros2CustomMessages'.Done.
    [1/1] Generating MATLAB interfaces for custom message packages... Done.
    Running colcon build in folder 'C:/Work/ros2CustomMessages/matlab_msg_gen/win64'.
    Build in progress. This may take several minutes...
    Build succeeded.build log
    Generating zip file in the folder 'C:/Work/ros2CustomMessages'.Done.
    

    Copy the generated custom messages in the ZIP archive to the target computer and register it using the ros2RegisterMessages function.

    ros2RegisterMessages(genDir)

    Run ros2 msg list on the target computer to view the custom messages for using in the workflow.

    Input Arguments

    collapse all

    Path to the folder that contains matlab_msg_gen.zip file, specified as a string scalar or a character vector. 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.

    Data Types: char | string

    Version History

    Introduced in R2022b