机器人 / 系统课时
编写最小 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 可以导入:
# 加载 Jazzy 环境并检查 Python 客户端库
source /opt/ros/jazzy/setup.bash
python3 -c 'import rclpy; print(rclpy.__name__)'预期输出:
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,写入以下完整程序:
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 的目录执行:
# 启动 Python 节点
python3 hello_node.py预期输出示例:
[INFO] [<TIME>] [hello_rclpy]: 节点已启动
[INFO] [<TIME>] [hello_rclpy]: 心跳 #1
[INFO] [<TIME>] [hello_rclpy]: 心跳 #2
[INFO] [<TIME>] [hello_rclpy]: 心跳 #3<TIME> 表示实际运行时生成的时间戳,每次执行都会不同。日志持续出现,说明 rclpy.spin(node) 正在调度定时器回调。若只创建定时器但不调用 spin() 或其他执行器调度方法,周期回调不会按预期运行。
保持第一个终端中的程序运行,再打开第二个终端:
# 另一个终端也需要加载 ROS 2 环境
source /opt/ros/jazzy/setup.bash
ros2 node list预期输出中包含:
/hello_rclpy实际列表可能还包含其他节点。前面的 / 表示该节点在根命名空间下的完整名称。节点刚启动时,ROS 2 发现机制可能需要短暂时间才能使它出现在列表中。
返回第一个终端按 Ctrl+C 结束程序,随后再次执行 ros2 node list。正常情况下,等待发现信息更新后,列表中不再出现 /hello_rclpy。这同时验证了节点的创建、运行和退出三个阶段。
理解初始化、回调和退出顺序
节点不是一个普通的无限循环脚本。它依赖 ROS 2 通信上下文、节点对象和执行器共同完成工作。程序运行时,各阶段具有明确的先后关系。

整个过程可以拆成以下六个动作:
rclpy.init(args=args)初始化 ROS 2 通信上下文,使节点能够使用底层通信资源。HelloNode()构造节点对象,调用Node基类初始化,并创建定时器。构造期间立即记录启动日志。rclpy.spin(node)让执行器持续处理该节点的就绪回调,包括每秒触发的on_timer()。- 用户按
Ctrl+C后,执行器停止运行。根据 ROS 2 版本和信号处理状态,可能表现为KeyboardInterrupt、ExternalShutdownException或上下文结束;示例兼容这些常见情况。 finally中调用destroy_node(),释放节点拥有的 ROS 实体和相关资源。- 通过
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 发现机制,以及退出清理流程能够正常结束。