机器人 / 系统课时
创建 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 都可用:
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'预期输出:
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 后才能通过包名找到新安装的入口。

下面的 --build-type ament_python 选择 Python 包构建方式,--dependencies rclpy 把客户端库依赖写入 package.xml,--node-name 同时生成节点文件和 setup.py 中的命令行入口:
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'预期输出(只摘录最后一行;创建工具还会打印生成文件的日志):
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 保存退出。
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>。下面用语法编译和文本检查避免漏改:
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'预期输出:
source and entry ok若没有输出,请分别检查 Python 语法、依赖声明和 setup.py 入口映射。setup.cfg 默认将脚本安装到 lib/robot_bringup_py,不要随意改成普通 Python 的 bin 目录,否则 ros2 run 可能找不到入口。
构建、加载并启动
回到工作区根目录构建。--packages-select 只构建指定包,--symlink-install 便于迭代 Python 源码;新增入口点或修改包元数据后仍须重新构建。加载安装环境的 source 只影响当前终端,不是一次永久配置。
cd ~/robot_ws
colcon build --symlink-install --packages-select robot_bringup_py
source install/setup.bash
ros2 pkg executables robot_bringup_py预期输出(保留关键行;<TIME> 代表因机器而异的构建耗时):
Starting >>> robot_bringup_py
Finished <<< robot_bringup_py [<TIME>]
Summary: 1 package finished [<TIME>]
robot_bringup_py heartbeat_node确认入口存在后,在当前终端运行:
ros2 run robot_bringup_py heartbeat_node预期输出(持续每秒增加一次,<TIME> 为实际日志时间戳):
[INFO] [<TIME>] [heartbeat_node]: heartbeat 1
[INFO] [<TIME>] [heartbeat_node]: heartbeat 2保持它运行,另开一个终端加载环境并查询节点:
source /opt/ros/jazzy/setup.bash
source ~/robot_ws/install/setup.bash
ros2 node list预期输出:
/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。