自定义 ROS 2 接口

目标： 定义自定义接口文件（.msg 和 .srv），并在 Python 和 C++ 节点中使用它们。

教程级别： 初级

预计时间： 20 分钟

背景

在之前的教程中，你已经通过消息和服务接口学习了话题与服务，并编写了简单的发布者/订阅者（C++/Python）和服务端/客户端（C++/Python）节点。那些示例中使用的接口都是预定义的。

使用预定义的接口固然方便，但有时你需要定义自己的消息和服务。本教程将介绍创建自定义接口最简单的方法。

前提条件

你应该已经有一个 ROS 2 工作空间。

本教程还会用到之前发布者/订阅者（C++ 和 Python）以及服务端/客户端（C++ 和 Python）教程中创建的功能包，用来测试新的自定义消息。

任务

1 创建新功能包

在本教程中，你将在一个独立的功能包中创建自定义 .msg 和 .srv 文件，然后在另一个功能包中使用它们。两个功能包应该在同一个工作空间中。

由于我们会复用之前教程中创建的发布者/订阅者和服务端/客户端功能包，请确保你处于同一个工作空间（ros2_ws/src）中，然后运行以下命令创建新功能包：

ros2 pkg create --build-type ament_cmake --license Apache-2.0 tutorial_interfaces

tutorial_interfaces 是新功能包的名称。自定义接口功能包必须是 ament_cmake 类型，但这并不影响你在其他类型的功能包中使用这些消息和服务。你可以在 ament_cmake 功能包中定义自定义接口，然后在 C++ 或 Python 节点中使用，最后一节会介绍具体做法。

.msg 和 .srv 文件必须分别放在名为 msg 和 srv 的目录中。在 ros2_ws/src/tutorial_interfaces 下创建这两个目录：

mkdir msg srv

2 创建自定义定义

2.1 msg 定义

在刚才创建的 tutorial_interfaces/msg 目录中，新建一个名为 Num.msg 的文件，内容只有一行，声明其数据结构：

int64 num

这条自定义消息用于传递一个名为 num 的 64 位整数。

在 tutorial_interfaces/msg 目录中再创建一个名为 Sphere.msg 的文件，内容如下：

geometry_msgs/Point center
float64 radius

这条自定义消息引用了另一个消息包中定义的消息（本例中为 geometry_msgs/Point）。

2.2 srv 定义

在 tutorial_interfaces/srv 目录中，创建一个名为 AddThreeInts.srv 的文件，包含以下请求和响应结构：

int64 a
int64 b
int64 c
---
int64 sum

这是你的自定义服务，接收名为 a、b 和 c 的三个整数，返回一个名为 sum 的整数。

3 `CMakeLists.txt`

要将定义好的接口转换为特定语言（如 C++ 和 Python）的代码，请在 CMakeLists.txt 中添加以下内容：

find_package(geometry_msgs REQUIRED)
find_package(rosidl_default_generators REQUIRED)

rosidl_generate_interfaces(${PROJECT_NAME}
  "msg/Num.msg"
  "msg/Sphere.msg"
  "srv/AddThreeInts.srv"
  DEPENDENCIES geometry_msgs # Add packages that above messages depend on, in this case geometry_msgs for Sphere.msg
)

注意：rosidl_generate_interfaces 的第一个参数（库名）必须以功能包名开头，例如直接使用 ${PROJECT_NAME} 或 ${PROJECT_NAME}_suffix。参见 https://github.com/ros2/rosidl/issues/441#issuecomment-591025515。

4 `package.xml`

接口在构建时依赖 rosidl_default_generators 来生成特定语言的代码，因此需要声明这一构建工具依赖。rosidl_default_runtime 是运行时依赖，用于在运行阶段使用这些接口。rosidl_interface_packages 是 tutorial_interfaces 功能包应归属的依赖组，通过 <member_of_group> 标签声明。

在 package.xml 的 <package> 元素内添加以下行：

<depend>geometry_msgs</depend>
<buildtool_depend>rosidl_default_generators</buildtool_depend>
<exec_depend>rosidl_default_runtime</exec_depend>
<member_of_group>rosidl_interface_packages</member_of_group>

5 构建 `tutorial_interfaces` 功能包

至此，自定义接口功能包的所有部分都已就绪，可以开始构建了。在工作空间根目录（~/ros2_ws）下运行以下命令：

Linux/macOS:

colcon build --packages-select tutorial_interfaces

Windows:

colcon build --merge-install --packages-select tutorial_interfaces

构建完成后，其他 ROS 2 功能包就能发现这些接口了。

6 确认 msg 和 srv 已创建成功

打开一个新终端，在工作空间（ros2_ws）下执行以下命令来 source：

Linux:

source install/setup.bash

macOS:

. install/setup.bash

Windows:

call install/setup.bat

接下来，使用 ros2 interface show 命令确认接口是否创建成功。终端输出应类似以下内容：

$ ros2 interface show tutorial_interfaces/msg/Num
int64 num

$ ros2 interface show tutorial_interfaces/msg/Sphere
geometry_msgs/Point center
        float64 x
        float64 y
        float64 z
float64 radius

$ ros2 interface show tutorial_interfaces/srv/AddThreeInts
int64 a
int64 b
int64 c
---
int64 sum

7 测试新接口

这一步可以复用之前教程中创建的功能包。只需对节点、CMakeLists.txt 和 package.xml 文件做一些简单修改，即可使用新接口。

7.1 用发布者/订阅者测试 `Num.msg`

修改之前教程中创建的发布者/订阅者功能包（C++ 或 Python），即可看到 Num.msg 的实际效果。由于消息类型从标准字符串改成了数字，输出会略有不同。

发布者

C++:

#include <chrono>
#include <memory>

#include "rclcpp/rclcpp.hpp"
#include "tutorial_interfaces/msg/num.hpp"                                            // CHANGE

using namespace std::chrono_literals;

class MinimalPublisher : public rclcpp::Node
{
public:
  MinimalPublisher()
  : Node("minimal_publisher"), count_(0)
  {
    publisher_ = this->create_publisher<tutorial_interfaces::msg::Num>("topic", 10);  // CHANGE

    auto timer_callback = [this](){
      auto message = tutorial_interfaces::msg::Num();                                   // CHANGE
      message.num = this->count_++;                                                     // CHANGE
      RCLCPP_INFO_STREAM(this->get_logger(), "Publishing: '" << message.num << "'");    // CHANGE
      publisher_->publish(message);
    };
    timer_ = this->create_wall_timer(500ms, timer_callback);
  }

private:
  rclcpp::TimerBase::SharedPtr timer_;
  rclcpp::Publisher<tutorial_interfaces::msg::Num>::SharedPtr publisher_;             // CHANGE
  size_t count_;
};

int main(int argc, char * argv[])
{
  rclcpp::init(argc, argv);
  rclcpp::spin(std::make_shared<MinimalPublisher>());
  rclcpp::shutdown();
  return 0;
}

Python:

import rclpy
from rclpy.executors import ExternalShutdownException
from rclpy.node import Node

from tutorial_interfaces.msg import Num                            # CHANGE


class MinimalPublisher(Node):

    def __init__(self):
        super().__init__('minimal_publisher')
        self.publisher_ = self.create_publisher(Num, 'topic', 10)  # CHANGE
        timer_period = 0.5  # seconds
        self.timer = self.create_timer(timer_period, self.timer_callback)
        self.i = 0

    def timer_callback(self):
        msg = Num()                                                # CHANGE
        msg.num = self.i                                           # CHANGE
        self.publisher_.publish(msg)
        self.get_logger().info('Publishing: "%d"' % msg.num)       # CHANGE
        self.i += 1


def main(args=None):
    try:
        with rclpy.init(args=args):
            minimal_publisher = MinimalPublisher()

            rclpy.spin(minimal_publisher)
    except (KeyboardInterrupt, ExternalShutdownException):
        pass


if __name__ == '__main__':
    main()

订阅者

C++:

#include <functional>
#include <memory>

#include "rclcpp/rclcpp.hpp"
#include "tutorial_interfaces/msg/num.hpp"                                       // CHANGE

using std::placeholders::_1;

class MinimalSubscriber : public rclcpp::Node
{
public:
  MinimalSubscriber()
  : Node("minimal_subscriber")
  {
    auto topic_callback = [this](const tutorial_interfaces::msg::Num & msg){     // CHANGE
      RCLCPP_INFO_STREAM(this->get_logger(), "I heard: '" << msg.num << "'");    // CHANGE
    };
    subscription_ = this->create_subscription<tutorial_interfaces::msg::Num>(    // CHANGE
      "topic", 10, topic_callback);
  }

private:
  rclcpp::Subscription<tutorial_interfaces::msg::Num>::SharedPtr subscription_;  // CHANGE
};

int main(int argc, char * argv[])
{
  rclcpp::init(argc, argv);
  rclcpp::spin(std::make_shared<MinimalSubscriber>());
  rclcpp::shutdown();
  return 0;
}

Python:

import rclpy
from rclpy.executors import ExternalShutdownException
from rclpy.node import Node

from tutorial_interfaces.msg import Num                        # CHANGE


class MinimalSubscriber(Node):

    def __init__(self):
        super().__init__('minimal_subscriber')
        self.subscription = self.create_subscription(
            Num,                                               # CHANGE
            'topic',
            self.listener_callback,
            10)
        self.subscription  # prevent unused variable warning

    def listener_callback(self, msg):
        self.get_logger().info('I heard: "%d"' % msg.num)  # CHANGE


def main(args=None):
    try:
        with rclpy.init(args=args):
            minimal_subscriber = MinimalSubscriber()

            rclpy.spin(minimal_subscriber)
    except (KeyboardInterrupt, ExternalShutdownException):
        pass


if __name__ == '__main__':
    main()

CMakeLists.txt

添加以下行（仅限 C++）：

#...

find_package(ament_cmake REQUIRED)
find_package(rclcpp REQUIRED)
find_package(tutorial_interfaces REQUIRED)                      # CHANGE

add_executable(talker src/publisher_lambda_function.cpp)
target_link_libraries(talker PUBLIC rclcpp::rclcpp tutorial_interfaces::tutorial_interfaces)    # CHANGE

add_executable(listener src/subscriber_lambda_function.cpp)
target_link_libraries(listener PUBLIC rclcpp::rclcpp tutorial_interfaces::tutorial_interfaces)  # CHANGE

install(TARGETS
  talker
  listener
  DESTINATION lib/${PROJECT_NAME})

ament_package()

package.xml

添加以下行：

C++:

<depend>tutorial_interfaces</depend>

Python:

<exec_depend>tutorial_interfaces</exec_depend>

完成上述编辑并保存所有更改后，构建功能包：

C++:

Linux/macOS:

colcon build --packages-select cpp_pubsub

Windows:

colcon build --merge-install --packages-select cpp_pubsub

Python:

Linux/macOS:

colcon build --packages-select py_pubsub

Windows:

colcon build --merge-install --packages-select py_pubsub

打开两个新终端，分别 source 工作空间，然后运行：

C++:

      ros2 run cpp_pubsub talker

      ros2 run cpp_pubsub listener

Python:

    ros2 run py_pubsub talker

    ros2 run py_pubsub listener

由于 Num.msg 只传递一个整数，talker 发布的应该是整数值，而非之前教程中的字符串：

[INFO] [minimal_publisher]: Publishing: '0'
[INFO] [minimal_publisher]: Publishing: '1'
[INFO] [minimal_publisher]: Publishing: '2'

7.2 用服务端/客户端测试 `AddThreeInts.srv`

修改之前教程中创建的服务端/客户端功能包（C++ 或 Python），即可看到 AddThreeInts.srv 的实际效果。由于请求从原来的两个整数改成了三个整数，输出会略有不同。

服务端

C++:

#include "rclcpp/rclcpp.hpp"
#include "tutorial_interfaces/srv/add_three_ints.hpp"                                        // CHANGE

#include <memory>

void add(const std::shared_ptr<tutorial_interfaces::srv::AddThreeInts::Request> request,     // CHANGE
          std::shared_ptr<tutorial_interfaces::srv::AddThreeInts::Response>       response)  // CHANGE
{
  response->sum = request->a + request->b + request->c;                                      // CHANGE
  RCLCPP_INFO(rclcpp::get_logger("rclcpp"), "Incoming request\na: %ld" " b: %ld" " c: %ld",  // CHANGE
                request->a, request->b, request->c);                                         // CHANGE
  RCLCPP_INFO(rclcpp::get_logger("rclcpp"), "sending back response: [%ld]", (long int)response->sum);
}

int main(int argc, char **argv)
{
  rclcpp::init(argc, argv);

  std::shared_ptr<rclcpp::Node> node = rclcpp::Node::make_shared("add_three_ints_server");   // CHANGE

  rclcpp::Service<tutorial_interfaces::srv::AddThreeInts>::SharedPtr service =               // CHANGE
    node->create_service<tutorial_interfaces::srv::AddThreeInts>("add_three_ints",  &add);   // CHANGE

  RCLCPP_INFO(rclcpp::get_logger("rclcpp"), "Ready to add three ints.");                     // CHANGE

  rclcpp::spin(node);
  rclcpp::shutdown();
}

Python:

from tutorial_interfaces.srv import AddThreeInts                                                           # CHANGE

import rclpy
from rclpy.executors import ExternalShutdownException
from rclpy.node import Node


class MinimalService(Node):

    def __init__(self):
        super().__init__('minimal_service')
        self.srv = self.create_service(AddThreeInts, 'add_three_ints', self.add_three_ints_callback)       # CHANGE

    def add_three_ints_callback(self, request, response):                                                  # CHANGE
        response.sum = request.a + request.b + request.c                                                   # CHANGE
        self.get_logger().info('Incoming request\na: %d b: %d c: %d' % (request.a, request.b, request.c))  # CHANGE

        return response

def main(args=None):
    try:
        with rclpy.init(args=args):
            minimal_service = MinimalService()

            rclpy.spin(minimal_service)
    except (KeyboardInterrupt, ExternalShutdownException):
        pass


if __name__ == '__main__':
    main()

客户端

C++:

#include "rclcpp/rclcpp.hpp"
#include "tutorial_interfaces/srv/add_three_ints.hpp"                                       // CHANGE

#include <chrono>
#include <cstdlib>
#include <memory>

using namespace std::chrono_literals;

int main(int argc, char **argv)
{
  rclcpp::init(argc, argv);

  std::shared_ptr<rclcpp::Node> node = rclcpp::Node::make_shared("add_three_ints_client");  // CHANGE
  rclcpp::Client<tutorial_interfaces::srv::AddThreeInts>::SharedPtr client =                // CHANGE
    node->create_client<tutorial_interfaces::srv::AddThreeInts>("add_three_ints");          // CHANGE

  auto request = std::make_shared<tutorial_interfaces::srv::AddThreeInts::Request>();       // CHANGE
  request->a = 41;
  request->b = 1;
  request->c = 1;                                                                           // CHANGE

  while (!client->wait_for_service(1s)) {
    if (!rclcpp::ok()) {
      RCLCPP_ERROR(rclcpp::get_logger("rclcpp"), "Interrupted while waiting for the service. Exiting.");
      return 0;
    }
    RCLCPP_INFO(rclcpp::get_logger("rclcpp"), "service not available, waiting again...");
  }

  auto result = client->async_send_request(request);
  // Wait for the result.
  if (rclcpp::spin_until_future_complete(node, result) ==
    rclcpp::FutureReturnCode::SUCCESS)
  {
    RCLCPP_INFO(rclcpp::get_logger("rclcpp"), "Sum: %ld", result.get()->sum);
  } else {
    RCLCPP_ERROR(rclcpp::get_logger("rclcpp"), "Failed to call service add_three_ints");    // CHANGE
  }

  rclcpp::shutdown();
  return 0;
}

Python:

from tutorial_interfaces.srv import AddThreeInts                            # CHANGE

import rclpy
from rclpy.executors import ExternalShutdownException
from rclpy.node import Node


class MinimalClientAsync(Node):

    def __init__(self):
        super().__init__('minimal_client_async')
        self.cli = self.create_client(AddThreeInts, 'add_three_ints')       # CHANGE
        while not self.cli.wait_for_service(timeout_sec=1.0):
            self.get_logger().info('service not available, waiting again...')
        self.req = AddThreeInts.Request()                                   # CHANGE

    def send_request(self):
        self.req.a = 41
        self.req.b = 1
        self.req.c = 1                                                      # CHANGE
        return self.cli.call_async(self.req)


def main(args=None):
    try:
        with rclpy.init(args=args):
            minimal_client = MinimalClientAsync()
            future = minimal_client.send_request()
            rclpy.spin_until_future_complete(minimal_client, future)
            response = future.result()
            minimal_client.get_logger().info(
                'Result of add_three_ints: for %d + %d + %d = %d' %                                # CHANGE
                (minimal_client.req.a, minimal_client.req.b, minimal_client.req.c, response.sum))  # CHANGE
    except (KeyboardInterrupt, ExternalShutdownException):
        pass


if __name__ == '__main__':
    main()

CMakeLists.txt

添加以下行（仅限 C++）：

#...

find_package(ament_cmake REQUIRED)
find_package(rclcpp REQUIRED)
find_package(tutorial_interfaces REQUIRED)         # CHANGE

add_executable(server src/add_two_ints_server.cpp)
target_link_libraries(server PUBLIC rclcpp::rclcpp tutorial_interfaces::tutorial_interfaces)  # CHANGE

add_executable(client src/add_two_ints_client.cpp)
target_link_libraries(client PUBLIC rclcpp::rclcpp tutorial_interfaces::tutorial_interfaces)  # CHANGE

install(TARGETS
  server
  client
  DESTINATION lib/${PROJECT_NAME})

ament_package()

package.xml

添加以下行：

C++:

<depend>tutorial_interfaces</depend>

Python:

<exec_depend>tutorial_interfaces</exec_depend>

完成上述编辑并保存所有更改后，构建功能包：

C++:

Linux/macOS:

colcon build --packages-select cpp_srvcli

Windows:

colcon build --merge-install --packages-select cpp_srvcli

Python:

Linux/macOS:

colcon build --packages-select py_srvcli

Windows:

colcon build --merge-install --packages-select py_srvcli

打开两个新终端，分别 source 工作空间，然后运行：

C++:

      ros2 run cpp_srvcli server

      ros2 run cpp_srvcli client

Python:

    ros2 run py_srvcli service

    ros2 run py_srvcli client

总结

在本教程中，你学习了如何在独立的功能包中创建自定义接口，以及如何在其他功能包中使用这些接口。

本教程只涵盖了自定义接口的基础内容。你可以在 ROS 2 接口文档中了解更详细的内容。

下一步

下一篇教程将介绍更多在 ROS 2 中使用接口的方法。

自定义 ROS 2 接口

背景

前提条件

任务

1 创建新功能包

2 创建自定义定义

2.1 msg 定义

2.2 srv 定义

3 CMakeLists.txt

4 package.xml

5 构建 tutorial_interfaces 功能包

6 确认 msg 和 srv 已创建成功

7 测试新接口

7.1 用发布者/订阅者测试 Num.msg

7.2 用服务端/客户端测试 AddThreeInts.srv

总结

下一步

3 `CMakeLists.txt`

4 `package.xml`

5 构建 `tutorial_interfaces` 功能包

7.1 用发布者/订阅者测试 `Num.msg`

7.2 用服务端/客户端测试 `AddThreeInts.srv`