机器人 / 系统课时

创建 colcon 工作区与功能包

创建 colcon 工作区与功能包

本课以 Ubuntu 24.04 和 ROS 2 Jazzy 为环境,建立 robot_ws 工作区和 Python 功能包,写出一个每秒记录心跳的节点,再完成构建、环境加载与启动。最终你可以用 ros2 run 运行它,并用 ROS 2 命令确认节点已被发现。

学习目标

  • 区分工作区的 src/、build/、install/ 和 log/。
  • 创建 ament_python 功能包并核对依赖与命令行入口。
  • 通过 colcon build、source 和 ros2 run 完成可验证的运行闭环。

核对 ROS 2 环境

以下命令在 Ubuntu 24.04 的 Bash 终端执行,前提是已安装 ROS 2 Jazzy。先加载系统级 ROS 环境并确认 ros2 和 colcon 都可用:

bash
source /opt/ros/jazzy/setup.bash
printf 'ROS_DISTRO=%s\n' "$ROS_DISTRO"
command -v ros2 >/dev/null && command -v colcon >/dev/null && echo 'toolchain ok'

预期输出:

text
ROS_DISTRO=jazzy
toolchain ok

如果找不到 /opt/ros/jazzy/setup.bash,说明当前机器未按该路径安装 Jazzy;不要直接执行后续构建。若只有 colcon 缺失,可通过 Ubuntu 软件包 python3-colcon-common-extensions 安装。每次新开终端都需要加载对应环境,除非你已自行配置自动加载。

创建工作区和功能包

工作区根目录用于执行 colcon,功能包源码放在 src/ 内。构建后同级生成 build/(中间文件)、install/(安装结果)和 log/(构建日志);终端加载 install/setup.bash 后才能通过包名找到新安装的入口。

colcon 工作区、功能包及运行环境的对应关系

下面的 --build-type ament_python 选择 Python 包构建方式,--dependencies rclpy 把客户端库依赖写入 package.xml,--node-name 同时生成节点文件和 setup.py 中的命令行入口:

bash
mkdir -p ~/robot_ws/src
cd ~/robot_ws/src
ros2 pkg create robot_bringup_py --build-type ament_python --license Apache-2.0 --dependencies rclpy --node-name heartbeat_node
test -f robot_bringup_py/robot_bringup_py/heartbeat_node.py && echo 'package skeleton ready'

预期输出(只摘录最后一行;创建工具还会打印生成文件的日志):

text
package skeleton ready

这里的功能包名是 robot_bringup_py,可执行入口名是 heartbeat_node,二者不能在 ros2 run 命令中互换。首次创建时使用空目录;已存在同名功能包时不要再次运行创建命令。

编写节点并检查入口

将生成的 ~/robot_ws/src/robot_bringup_py/robot_bringup_py/heartbeat_node.py 替换为以下完整代码。可以用 nano 打开该文件,粘贴后按 Ctrl+O、回车、Ctrl+X 保存退出。

python
import rclpy
from rclpy.node import Node

class HeartbeatNode(Node):
    def __init__(self):
        super().__init__('heartbeat_node')
        self.count = 0
        # 1 秒定时器用于证明节点回调正在被执行。
        self.timer = self.create_timer(1.0, self.on_timer)

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

def main(args=None):
    rclpy.init(args=args)
    node = HeartbeatNode()
    try:
        rclpy.spin(node)  # 持续调度回调,直到终端中断。
    except KeyboardInterrupt:
        pass
    finally:
        node.destroy_node()
        if rclpy.ok():
            rclpy.shutdown()

if __name__ == '__main__':
    main()

这是功能包内的源文件,需经构建和入口注册后用 ros2 run 调用。创建命令已在 setup.py 的 console_scripts 中注册 heartbeat_node = robot_bringup_py.heartbeat_node:main;package.xml 应含 <depend>rclpy</depend>。下面用语法编译和文本检查避免漏改:

bash
cd ~/robot_ws/src/robot_bringup_py
python3 -m py_compile robot_bringup_py/heartbeat_node.py &&
grep -Fq '<depend>rclpy</depend>' package.xml &&
grep -Fq 'heartbeat_node = robot_bringup_py.heartbeat_node:main' setup.py &&
echo 'source and entry ok'

预期输出:

text
source and entry ok

若没有输出,请分别检查 Python 语法、依赖声明和 setup.py 入口映射。setup.cfg 默认将脚本安装到 lib/robot_bringup_py,不要随意改成普通 Python 的 bin 目录,否则 ros2 run 可能找不到入口。

构建、加载并启动

回到工作区根目录构建。--packages-select 只构建指定包,--symlink-install 便于迭代 Python 源码;新增入口点或修改包元数据后仍须重新构建。加载安装环境的 source 只影响当前终端,不是一次永久配置。

bash
cd ~/robot_ws
colcon build --symlink-install --packages-select robot_bringup_py
source install/setup.bash
ros2 pkg executables robot_bringup_py

预期输出(保留关键行;<TIME> 代表因机器而异的构建耗时):

text
Starting >>> robot_bringup_py
Finished <<< robot_bringup_py [<TIME>]
Summary: 1 package finished [<TIME>]
robot_bringup_py heartbeat_node

确认入口存在后,在当前终端运行:

bash
ros2 run robot_bringup_py heartbeat_node

预期输出(持续每秒增加一次,<TIME> 为实际日志时间戳):

text
[INFO] [<TIME>] [heartbeat_node]: heartbeat 1
[INFO] [<TIME>] [heartbeat_node]: heartbeat 2

保持它运行,另开一个终端加载环境并查询节点:

bash
source /opt/ros/jazzy/setup.bash
source ~/robot_ws/install/setup.bash
ros2 node list

预期输出:

text
/heartbeat_node

发现节点可能需要短暂等待。验证完成后回到运行节点的终端,按 Ctrl+C 停止。

定位构建与启动失败

遇到 Package 'robot_bringup_py' not found,先确认构建成功,再在执行 ros2 run 的那个终端重新运行 source ~/robot_ws/install/setup.bash。若仍不可见,用 ros2 pkg list 检查包是否已进入环境;不要把 source 当成重新编译。

遇到 No executable found,检查 setup.py 中的 console_scripts 是否包含 heartbeat_node = robot_bringup_py.heartbeat_node:main,以及 setup.cfg 是否将入口安装到 lib/robot_bringup_py;修正后重新执行上一节的构建和加载命令。

遇到 ModuleNotFoundError: No module named 'rclpy',先核对 ROS_DISTRO 是否为 jazzy、当前 Python 环境是否与 ROS 安装兼容,并确认没有误用其他虚拟环境的解释器。若新添了第三方依赖,需将其声明在包元数据中并完成相应安装,单写 import 不会让 colcon 自动下载库。

成功标准是:构建汇总显示一个功能包完成、ros2 pkg executables 列出入口、节点连续打印递增心跳,并且 ros2 node list 能看见 /heartbeat_node。

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

目录与阅读设置

阅读设置

17

记录一个想法

创建 colcon 工作区与功能包

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

登录哪都通