ROS2（二）：第一个自定义 Python 节点从编写到运行

1. 本节目标

完成一个“最小可运行”的 ROS2 Python 节点，并理解完整开发流程：

1. 在包内编写节点代码
2. 在 setup.py 注册可执行入口
3. 使用 colcon build 构建
4. source install/setup.bash 加载工作区
5. 使用 ros2 run 启动节点

2. 为什么要这样做

在 ROS2 中，Python 文件“能运行”不代表“能被 ROS2 识别运行”。

要让命令 ros2 run <包名> <可执行名> 成立，必须满足：

• 代码文件存在于 Python 包目录
• setup.py 中 console_scripts 注册了入口映射
• 包已构建并安装到 install/
• 当前终端已加载工作区环境

这就是 ROS2 工程化流程和普通 Python 脚本最大的区别。

3. 代码放在哪里

本节包名：py_pubsub_demo
节点文件位置：

src/py_pubsub_demo/py_pubsub_demo/hello_node.py

说明：

• 第一个 py_pubsub_demo 是 ROS2 包目录
• 第二个 py_pubsub_demo 是 Python 模块目录

4. 最小节点代码结构解析

本节节点包含 4 个关键部分：

4.1 继承 Node

class HelloNode(Node):

• 只有继承 Node，这个类才具有 ROS2 节点能力（日志、定时器、参数等）

4.2 给节点命名

super().__init__('hello_node')

• 节点名是 ROS 图中的身份标识
• 运行后可通过 ros2 node list 看到 /hello_node

4.3 定时器 + 回调

self.timer = self.create_timer(1.0, self.timer_callback)

• 每 1 秒调用一次回调函数
• 回调中用日志打印“第几次问候”

4.4 标准启动入口 main()

rclpy.init()
node = HelloNode()
rclpy.spin(node)
node.destroy_node()
rclpy.shutdown()

• init：初始化 ROS2
• spin：让节点持续处理回调
• destroy_node + shutdown：优雅退出

5. setup.py 入口注册是关键步骤

在 setup.py 里注册：

'hello_node = py_pubsub_demo.hello_node:main'

含义拆解：

• 左边 hello_node：ros2 run 时使用的可执行名

• 右边 py_pubsub_demo.hello_node:main：

  • 模块路径 py_pubsub_demo/hello_node.py
  • 调用函数 main

没有这一步，ros2 run 找不到自定义节点。

6. 标准开发流程（建议记成固定模板）

每次写完节点，按以下顺序执行：

1. cd ~/ros2_ws
2. source /opt/ros/jazzy/setup.bash
3. colcon build
4. source install/setup.bash
5. ros2 run py_pubsub_demo hello_node

这是初学阶段最稳定的流程。

7. 本节实际验证结果

构建成功后，节点按 1Hz 输出日志：

• 你好 ROS2，第 0 次问候
• 你好 ROS2，第 1 次问候
• 你好 ROS2，第 2 次问候

说明以下链路全部成功：

• 代码可执行
• 入口可解析
• ROS2 节点运行正常
• 定时器回调生效

8. 常见错误与定位

错误 1：No executable found

原因：setup.py 没注册或注册名写错。
检查：console_scripts 是否包含正确映射。

错误 2：改了代码但运行还是旧行为

原因：改完没重新 build / 没 source install。
修复：重新执行“构建 + source install”。

错误 3：colcon: command not found

原因：构建工具未安装。
修复：安装 python3-colcon-common-extensions。

9. 本节知识点小结

本节完成后应能明确：

• ROS2 Python 节点是一个继承 Node 的类
• 节点常见执行模型是“定时器 + 回调”
• setup.py 的 console_scripts 决定 ros2 run 能否找到入口
• ROS2 开发是“写代码 → 注册入口 → 构建 → source → 运行”的工程闭环