ROS2-004-Communication Mechanisms: Topic Communication Extra: How to Implement a Custom Interface Message

Introduction

The flow for implementing a custom topic interface message is similar to the flow for writing an executable in a package. The main steps are:

1. Create and write the .msg file;
2. Edit the configuration files;
3. Build;
4. Test.

So we'll now go into the interface package base_interfaces_demo we created earlier and try writing a .msg file. That file will hold a student's name, age, height and so on.

Creating and editing the .msg file

Under the package base_interfaces_demo, create a msg folder, and under msg create a Student.msg file, with the following content:

string name
int32 age
float64 height

Editing the configuration files

1. The package.xml file

In package.xml you need to add a few dependency packages, specifically:

<!-- build dependency -->
<build_depend>rosidl_default_generators</build_depend>
<!-- execution dependency -->
<exec_depend>rosidl_default_runtime</exec_depend>
<!-- declare the package group this package belongs to -->
<member_of_group>rosidl_interface_packages</member_of_group>

2. The CMakeLists.txt file

To turn the .msg file into the corresponding C++ and Python code, you also need to add the following configuration to CMakeLists.txt:

find_package(rosidl_default_generators REQUIRED)
# generate source code for the interface file
rosidl_generate_interfaces(${PROJECT_NAME}
    "msg/Student.msg"
)

Build

In a terminal, go into the current workspace and build the package:

colcon build --packages-select base_interfaces_demo

Test

Once the build finishes, the C++ and Python files corresponding to Student.msg are generated in the install directory of the workspace. You can also go into the workspace from a terminal and check the file definition and whether the build went fine with:

. install/setup.bash
ros2 interface show base_interfaces_demo/msg/Student

And with that, the creation work is done.

including a custom interface file may throw errors

Once the creation work is done, you'll want to include the headers related to the custom message in a C++ file. At that point VSCode may throw an exception at you. You can open the c_cpp_properties.json file in VSCode and add one path line under the includePath property:

"${workspaceFolder}/install/base_interfaces_demo/include/**"

Once that's added, the exception won't be thrown when you include the relevant headers. The same goes for using other interface files or interface packages.

customising imports in Python files

When importing the packages related to a custom message in a Python file, for convenience you can configure the settings.json file in VSCode and add one line under the python.autoComplete.extraPaths and python.analysis.extraPaths properties:

"${workspaceFolder}/install/base_interfaces_demo/lib/python3.12/site-packages"

Once that's added, the code highlights properly and autocompletes, and the same goes for using other interface files or interface packages.

(Note: the ROS2 version used here is Jazzy and Python is 3.12, so the path structure may not match yours — change and create it according to your own project tree.)

---

Tips

If you came here from ROS2-004-Communication Mechanisms: Topic Communication — Branch Two — Custom Message Interfaces, you can navigate back from here.

Important

This article was translated by Hermes Agent; the original text can be found at here. The translation is for reference only. Translation time: 2026-11-05