机器人 / 系统课时

创建 ament_python 功能包

创建 ament_python 功能包

用 ROS 2 Jazzy 创建 Python 功能包 robot_comm,声明通信依赖、检查安装配置,再通过构建与运行确认功能包可被发现。完成后能区分包元数据、源码目录和可执行入口的职责。

学习目标

  • 使用 ros2 pkg create 创建带依赖和示例节点的 ament_python 包。
  • 区分包元数据、Python 模块、资源索引与可执行入口的职责。
  • 用 colcon 构建并验证包和节点的安装结果。

在工作区生成包骨架

以下命令适用于 Ubuntu 24.04、已安装 ROS 2 Jazzy 和 colcon 的 Bash 终端。ROS 工作区以 ~/ros2_ws 为例;必须进入工作区的 src,不要在已有包内部再创建包。

bash
# 新终端先加载 ROS 2 环境
source /opt/ros/jazzy/setup.bash
echo "$ROS_DISTRO"
mkdir -p ~/ros2_ws/src
cd ~/ros2_ws/src
# 同时生成示例节点,便于后续验证安装入口
ros2 pkg create --build-type ament_python --license Apache-2.0 --node-name demo_node robot_comm --dependencies rclpy std_msgs

预期输出(节选):

text
jazzy
going to create a new package
package name: robot_comm
build type: ament_python

--build-type ament_python 选择 Python 包构建方式;--node-name demo_node 生成最小示例节点;--dependencies 将 rclpy、std_msgs 写入包清单,但不会自动安装缺失的软件包。若提示目标目录已存在,先检查其中的文件,不要覆盖已有工程。

认清生成的目录

新建的包根目录为 ~/ros2_ws/src/robot_comm,其中又有同名的 robot_comm/ 目录:外层是 ROS 功能包,内层是可被 Python 导入的模块。无需手工补建这些文件。

路径 用途
package.xml 声明 ROS 包名、版本、维护者、许可、依赖和构建类型
robot_comm/__init__.py 标记 Python 模块
robot_comm/demo_node.py --node-name 自动生成的示例入口代码
resource/robot_comm ROS 包索引的资源标记;可为空文件
setup.py 规定 Python 模块、资源文件和命令行入口如何安装
setup.cfg 规定节点脚本在安装目录中的位置
test/ 自动生成的测试与代码检查文件

ament_python 包通常没有 CMakeLists.txt。如果生成的是 ament_cmake 结构,检查创建命令中的 --build-type,不要直接把 C++ 包的目录布局套到 Python 包上。

校对依赖和包元数据

打开 ~/ros2_ws/src/robot_comm/package.xml,确认包名为 robot_comm,构建类型为 ament_python,依赖中有 <depend>rclpy</depend> 和 <depend>std_msgs</depend>。前者提供 Python 节点 API,后者提供后续收发字符串消息所需的消息类型。

将 <description> 从 TODO 改成实际用途,例如“ROS 2 Python 节点通信练习”;核实 <maintainer> 的姓名与邮箱是你可维护的信息,并让 <license> 与实际采用的许可证一致。setup.py 中的 name、version、description、maintainer、maintainer_email、license 也要与包清单一致;这里的维护者信息不能长期保留自动生成的占位值。

这两份文件的侧重点不同:package.xml 告诉 ROS 工具如何识别、解析依赖;setup.py 告诉 Python 打包工具如何安装模块。不要只在 setup.py 的 install_requires 中填写 rclpy,就认为 ROS 的依赖声明已经完成。

理解可执行入口的安装

生成的 setup.py 应含有 console_scripts 入口 demo_node = robot_comm.demo_node:main;它把命令名关联到 demo_node.py 的 main()。data_files 负责安装包索引标记和 package.xml。setup.cfg 应包含以下完整配置;如果包名改过,两个路径都要同步修改。

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

这会把节点入口放到 ROS 2 查找的 lib/robot_comm 下;setup.py 只声明 console_scripts 而安装路径错误时,可能出现找得到包却找不到可执行文件。

ament_python 包文件与安装结果的关系

构建并检查结果

回到工作区根目录,只构建刚创建的包。--symlink-install 便于开发时修改 Python 源码,但改动入口或打包配置后仍需重新构建。

bash
cd ~/ros2_ws
colcon build --packages-select robot_comm --symlink-install

预期结果:构建日志含 Summary: 1 package finished;实际耗时可能不同。构建成功后,在当前终端加载工作区覆盖层并运行示例节点。

bash
source install/setup.bash
ros2 pkg prefix robot_comm
ros2 pkg executables robot_comm
ros2 run robot_comm demo_node

预期输出(第一行是因机器而异的安装路径):

text
<PATH>
robot_comm demo_node
Hi from robot_comm.

如果 ros2 pkg prefix 提示包不存在,确认命令在 ~/ros2_ws 构建成功,并在当前终端执行了 source install/setup.bash。如果能找到包却提示 No executable found,先核对 setup.py 的 console_scripts、demo_node.py 中的 main() 和 setup.cfg 的两个安装路径,再重新构建并加载环境。这个验证说明包已安装且入口可执行,并不代表示例节点已经实现话题通信。

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

目录与阅读设置

阅读设置

17

记录一个想法

创建 ament_python 功能包

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

登录哪都通