机器人 / 系统课时

编写最小 rclpy 节点

编写最小 rclpy 节点

一个 ROS 2 Python 程序必须先初始化通信上下文,再创建节点并处理回调,退出时还要释放资源。本课编写一个可直接运行的 rclpy 节点,让它启动后输出日志、每秒打印一次心跳,并通过 ROS 2 命令验证节点确实存在。

学习目标

  • 使用 rclpy.init() 和 Node 创建具有固定名称的 ROS 2 节点。
  • 理解 rclpy.spin() 如何调度回调,以及节点日志何时产生。
  • 使用 destroy_node() 和 rclpy.shutdown() 正确清理资源,并验证节点的启动与退出。

检查 Python 与 ROS 2 环境

以下操作以 Ubuntu 24.04 和 ROS 2 Jazzy 为例。需要已经安装 ROS 2,并使用系统 Python 3。其他 ROS 2 发行版应将命令中的 jazzy 替换为实际发行版名称。

打开终端,加载 ROS 2 环境并验证 rclpy 可以导入:

bash
# 加载 Jazzy 环境并检查 Python 客户端库
source /opt/ros/jazzy/setup.bash
python3 -c 'import rclpy; print(rclpy.__name__)'

预期输出:

text
rclpy

这说明当前 Python 解释器能够找到 ROS 2 的 Python 客户端库。rclpy 提供节点创建、定时器、话题、服务和执行器等接口。本课只使用节点、日志和定时器,不依赖第三方 Python 包。

如果提示 ModuleNotFoundError: No module named 'rclpy',先检查 /opt/ros/jazzy/setup.bash 是否存在、是否已经加载环境,以及 python3 是否指向与 ROS 2 安装兼容的解释器。不要直接通过普通 pip install rclpy 代替 ROS 2 系统安装。

编写可以持续运行的节点

在当前工作目录创建文件 hello_node.py,写入以下完整程序:

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


class HelloNode(Node):
    def __init__(self):
        super().__init__('hello_rclpy')
        self.count = 0
        # 注册每秒执行一次的定时器回调
        self.timer = self.create_timer(1.0, self.on_timer)
        self.get_logger().info('节点已启动')

    def on_timer(self):
        self.count += 1
        self.get_logger().info(f'心跳 #{self.count}')


def main(args=None):
    # 先初始化 ROS 通信上下文,再创建节点
    rclpy.init(args=args)
    node = HelloNode()
    try:
        rclpy.spin(node)
    except (KeyboardInterrupt, ExternalShutdownException):
        pass
    finally:
        # 先释放节点,必要时再关闭通信上下文
        node.destroy_node()
        if rclpy.ok():
            rclpy.shutdown()


if __name__ == '__main__':
    main()

预期结果:执行该脚本后,节点立即输出启动日志,随后大约每秒输出一次递增的心跳日志。程序不会在打印第一条日志后自动退出,而是持续等待并处理回调,直到收到退出信号。

这里有三个关键 API:

  • Node:ROS 2 节点基类,super().__init__('hello_rclpy') 初始化节点并指定名称。名称中使用字母、数字和下划线,避免空格或不合法字符。
  • get_logger().info():通过 ROS 2 日志系统输出 INFO 级别消息。日志默认包含级别、时间戳和节点名称,比普通 print() 更方便定位运行问题。
  • create_timer(1.0, self.on_timer):创建周期为 1.0 秒的定时器。它负责让回调具备触发条件,实际调用由执行器调度,执行周期并非严格实时保证。

self.timer 保存定时器对象的引用,便于后续管理。self.count 则保存节点对象自己的运行状态,每次执行 on_timer() 时递增。

运行程序并验证节点

在保存 hello_node.py 的目录执行:

bash
# 启动 Python 节点
python3 hello_node.py

预期输出示例:

text
[INFO] [<TIME>] [hello_rclpy]: 节点已启动
[INFO] [<TIME>] [hello_rclpy]: 心跳 #1
[INFO] [<TIME>] [hello_rclpy]: 心跳 #2
[INFO] [<TIME>] [hello_rclpy]: 心跳 #3

<TIME> 表示实际运行时生成的时间戳,每次执行都会不同。日志持续出现,说明 rclpy.spin(node) 正在调度定时器回调。若只创建定时器但不调用 spin() 或其他执行器调度方法,周期回调不会按预期运行。

保持第一个终端中的程序运行,再打开第二个终端:

bash
# 另一个终端也需要加载 ROS 2 环境
source /opt/ros/jazzy/setup.bash
ros2 node list

预期输出中包含:

text
/hello_rclpy

实际列表可能还包含其他节点。前面的 / 表示该节点在根命名空间下的完整名称。节点刚启动时,ROS 2 发现机制可能需要短暂时间才能使它出现在列表中。

返回第一个终端按 Ctrl+C 结束程序,随后再次执行 ros2 node list。正常情况下,等待发现信息更新后,列表中不再出现 /hello_rclpy。这同时验证了节点的创建、运行和退出三个阶段。

理解初始化、回调和退出顺序

节点不是一个普通的无限循环脚本。它依赖 ROS 2 通信上下文、节点对象和执行器共同完成工作。程序运行时,各阶段具有明确的先后关系。

rclpy 节点初始化、执行器回调与资源释放的生命周期

整个过程可以拆成以下六个动作:

  1. rclpy.init(args=args) 初始化 ROS 2 通信上下文,使节点能够使用底层通信资源。
  2. HelloNode() 构造节点对象,调用 Node 基类初始化,并创建定时器。构造期间立即记录启动日志。
  3. rclpy.spin(node) 让执行器持续处理该节点的就绪回调,包括每秒触发的 on_timer()。
  4. 用户按 Ctrl+C 后,执行器停止运行。根据 ROS 2 版本和信号处理状态,可能表现为 KeyboardInterrupt、ExternalShutdownException 或上下文结束;示例兼容这些常见情况。
  5. finally 中调用 destroy_node(),释放节点拥有的 ROS 实体和相关资源。
  6. 通过 rclpy.ok() 检查上下文是否仍有效;如果有效,再调用 rclpy.shutdown() 完成关闭。若信号处理器已关闭上下文,则避免重复关闭。

rclpy.init() 和 rclpy.shutdown() 管理的是通信上下文,Node 与 destroy_node() 管理的是具体节点对象。二者职责不同,不应把销毁节点当成关闭整个 ROS 2 上下文。

定位最常见的运行问题

现象 可能原因 修复与检查
No module named 'rclpy' 未加载 ROS 2 环境或 Python 环境不匹配 重新执行 source /opt/ros/jazzy/setup.bash,检查 python3 的实际路径
只看到启动日志,没有心跳日志 未执行 spin()、定时器未成功创建或执行器被阻塞 检查 create_timer(1.0, self.on_timer) 和 rclpy.spin(node) 是否执行
ros2 node list 找不到节点 程序已经退出、ROS 环境或发现配置不一致 确认进程仍运行,检查两端 ROS_DOMAIN_ID 是否一致,并稍等发现完成
节点已经停止但列表仍暂时显示 ROS 2 发现信息尚未更新 等待片刻后重新运行 ros2 node list
Ctrl+C 后出现异常堆栈 未处理执行器停止时产生的中断异常 使用示例中的 except 和 finally,确保退出路径包含节点清理

还要区分节点脚本能够直接运行与功能包能够通过 ros2 run 运行:本课的 python3 hello_node.py 不要求创建 ROS 2 功能包。如果要改成 ros2 run <包名> <可执行名>,则还需要 ament_python 功能包、对应的 console_scripts 入口和安装构建步骤,仅保存一个 Python 文件并不会自动注册为 ROS 2 可执行入口。

完成验证时,应同时满足三个条件:终端持续输出心跳日志、第二个终端能够发现 /hello_rclpy、按 Ctrl+C 后节点从列表中消失。这三个结果分别证明代码已经进入回调循环、节点已参与 ROS 2 发现机制,以及退出清理流程能够正常结束。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

编写最小 rclpy 节点

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通