机器人 / 系统课时

注册入口并通过 ros2 run 启动

注册入口并通过 ros2 run 启动

Python 节点能运行,不代表 ros2 run 能找到它。ROS 2 查找的是安装后的入口脚本,而非源码文件。本篇用 Jazzy 的 ament_python 包演示注册、构建、启动与排错。

学习目标

  • 区分功能包名、console_scripts 可执行名、Python 模块与 main() 函数。
  • 正确设置 setup.py、检查 setup.cfg,并使用 colcon build 和 ros2 run 验收入口。
  • 根据“找不到可执行文件”和 Python 导入异常选择不同的修复方向。

准备功能包与最小节点

先确认系统已安装 Jazzy 与 colcon。本例在 Bash 终端新建 py_nodes 包,假定 ~/ros2_ws/src/py_nodes 尚不存在;若已有同名包,直接沿用并检查它的构建类型是否为 ament_python。

bash
source /opt/ros/jazzy/setup.bash
mkdir -p ~/ros2_ws/src
cd ~/ros2_ws/src
ros2 pkg create --build-type ament_python --license Apache-2.0 py_nodes --dependencies rclpy

预期结果:命令成功创建 ~/ros2_ws/src/py_nodes/,其中包含 package.xml、setup.py、setup.cfg、resource/py_nodes 和 py_nodes/__init__.py。实际创建提示与终端路径可能不同。

在 ~/ros2_ws/src/py_nodes/py_nodes/hello_node.py 新建以下完整文件。这里让节点只输出一条日志并立即退出,便于判断 main() 是否真正被入口调用。

python
import rclpy
from rclpy.node import Node

def main(args=None):
    rclpy.init(args=args)
    node = Node('hello_node')
    try:
        # 使用 ROS 日志而不是普通 print,验证节点已正常初始化
        node.get_logger().info('console_scripts is working')
    finally:
        # 短生命周期示例必须主动释放 ROS 资源
        node.destroy_node()
        rclpy.shutdown()

if __name__ == '__main__':
    main()

预期结果:保存源码不会产生终端输出;通过后面的 ros2 run 启动时会打印 console_scripts is working 并退出。由于进程很快结束,通常无法靠 ros2 node list 捕获它,应以日志验收。

在 setup.py 注册可执行入口

将新建包的 setup.py 改为以下完整内容。console_scripts 等号左侧是交给 ros2 run 的可执行名;右侧 py_nodes.hello_node:main 表示导入 Python 模块 py_nodes.hello_node 并调用其中的 main()。

python
from setuptools import find_packages, setup

package_name = 'py_nodes'

setup(
    name=package_name,
    version='0.0.0',
    packages=find_packages(exclude=['test']),
    data_files=[
        # ament 索引负责让 ROS 2 找到已安装的功能包
        ('share/ament_index/resource_index/packages', ['resource/' + package_name]),
        ('share/' + package_name, ['package.xml']),
    ],
    install_requires=['setuptools'],
    zip_safe=True,
    maintainer='ros2_learner',
    maintainer_email='maintainer@example.com',
    description='Minimal rclpy console entry example',
    license='Apache-2.0',
    entry_points={
        'console_scripts': [
            # 可执行名 = Python 包.模块:函数
            'hello_node = py_nodes.hello_node:main',
        ],
    },
)

生效行为:下一次构建会安装名为 hello_node 的入口包装脚本,后续用 ros2 pkg executables py_nodes 验证。maintainer 和 maintainer_email 是示例元数据,实际项目请替换;resource/py_nodes 与声明 rclpy 依赖的 package.xml 必须保留。源码 .py 不需要额外执行 chmod +x。

再确认自动生成的 setup.cfg 包含以下配置。它告诉安装器把入口脚本放到 ROS 2 预期的 lib/py_nodes 目录,而不是普通的 bin 目录。

ini
[develop]
script_dir=$base/lib/py_nodes
[install]
install_scripts=$base/lib/py_nodes

生效行为:构建时入口脚本会安装到功能包的 lib/py_nodes 下;下面通过命令查询可执行入口是否存在。

console_scripts 入口从构建到运行的调用关系

重新构建并验证 ros2 run

从工作空间根目录构建,而不是在 Python 模块目录执行 colcon。修改 setup.py 中的入口映射后必须重新构建;即使使用 --symlink-install,入口元数据变化也不能仅靠保存源码生效。

bash
cd ~/ros2_ws
colcon build --packages-select py_nodes
source install/setup.bash
ros2 pkg executables py_nodes

预期输出(构建耗时是动态值,记作 <TIME>;此处只展示关键行):

text
Starting >>> py_nodes
Finished <<< py_nodes [<TIME>]
Summary: 1 package finished [<TIME>]
py_nodes hello_node

最后一行是判断入口是否已注册的直接证据。py_nodes 是功能包名,hello_node 是可执行入口名;两者与 Python 文件名并不要求一致,只须与入口映射对应。

bash
ros2 run py_nodes hello_node

预期输出(日志时间戳因运行环境不同,以 <TIME> 代替):

text
[INFO] [<TIME>] [hello_node]: console_scripts is working

该命令正常打印一次日志并退出,说明已成功从 ROS 2 功能包定位可执行入口、导入模块并调用 main()。

根据报错定位入口问题

不要把“找不到可执行文件”和“找不到 Python 模块”当成一类故障。先看 ros2 pkg executables py_nodes 是否列出了入口,再判断错误发生在入口发现阶段,还是入口启动后的 Python 导入阶段。

现象 优先检查 修复方法
Package 'py_nodes' not found 工作空间是否构建、终端是否加载 install/setup.bash 在工作空间根目录构建并重新 source
No executable found setup.py 的 console_scripts、setup.cfg 的 lib/py_nodes 路径 核对入口名,重新构建并加载工作空间
ModuleNotFoundError 是否存在 py_nodes/py_nodes/hello_node.py,模块路径是否拼错 修正等号右侧的模块路径并重建
AttributeError 提示找不到 main 模块中是否定义了顶层 def main(args=None) 补齐函数或修正冒号后的名称并重建

例如注册名是 hello_node,却执行 ros2 run py_nodes hello,也会遇到 No executable found;应修正执行名,而不是改节点名称。如果工作空间存在多个同名功能包,还要检查 ros2 pkg prefix py_nodes 指向哪里:它应返回当前工作空间的安装前缀,而不是另一份旧包。入口能够列出却启动失败时,优先排查模块与函数;入口连列出都做不到时,优先排查注册、构建与环境加载。

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

目录与阅读设置

阅读设置

17

记录一个想法

注册入口并通过 ros2 run 启动

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

登录哪都通