ROS2 工作空间与功能包开发规范

关联：索引

ROS2 工作空间，简单说就是“放 ROS2 项目所有文件的文件夹”。你手动创建的一般只有 src，当你执行 colcon build 之后，工作空间根目录通常会出现 src/build/install/log 这四类目录，各自功能很明确，记好下面的内容即可。

• src：源码目录（最核心，要手动管）
  作用：所有功能包的代码都放在这里，不管是自己写的，还是下载的别人的开源代码，都存在这个目录里。
  关键提醒：只有这个目录需要我们手动创建、手动放文件，其他3个目录，编译时会自动生成，不用我们动。

• build：编译目录（自动生成，不用管）
  作用：编译时产生的“中间文件”都在这里，比如编译日志、临时文件。
  关键提醒：编译报错时，老师会教大家看这里的日志找问题；平时不用碰这个目录，删了重新编译就能恢复。

• install：安装发布目录（核心，运行必须用）
  作用：最终编译好的“成品文件”都在这里，相当于项目的“发布版本”。
  关键提醒：每次编译完，要输一句 source install/setup.bash，电脑才能识别到我们编译好的内容（记好这句指令！）。

• log：日志目录（自动生成，排错用）
  作用：存放 colcon 编译过程的详细日志，编译失败时可以去这里找原因。
  关键提醒：如果编译报错但 build 没看懂，可以来这里看更详细的 log。

补充：老师会展示 AI 生成的目录结构示意图，大家对照图，记清4个目录的层级关系，不用自己画。

跟着老师的步骤，在终端输指令，一步都别错，做好记录，课后能独立操作就算掌握！

1. 分步操作（抄好指令，标清步骤）

0. 步骤0：激活 ROS2 Humble 环境（每次开新终端先做）
   指令：source /opt/ros/humble/setup.bash
   检查：echo $ROS_DISTRO（输出 humble 才算对）

1. 步骤1：创建工作空间根目录（建议叫 ros2_ws，全小写+下划线，符合规范）
   指令：mkdir -p ~/ros2_ws/src
   说明：-p 是“递归创建”，确保 src 文件夹在 ros2_ws 里面，不用自己手动建两层。

2. 步骤2：进入工作空间根目录（必须进对目录，否则后续操作报错）
   指令：cd ~/ros2_ws

3. 步骤3：安装依赖（推荐，尤其是你从网上拷贝了别人的包到 src 里）rosdep是ROS里专门用来自动安装软件包依赖的命令行工具。
   指令：rosdep install --from-paths src --ignore-src -r -y
   说明：没装 rosdep 的情况下先装：sudo apt install python3-rosdep，然后初始化：sudo rosdep init && rosdep update（离线环境可跳过本步）

4. 步骤4：编译工作空间（核心指令，记牢！）
   指令：colcon build --symlink-install
   说明：输完后，会自动生成 build、install、log 三个目录，耐心等编译完成（出现 [100%] 就是成功）。

5. 步骤5：激活工作空间环境（每次打开新终端，都要输一次！）
   指令：source install/setup.bash
   关键提醒：不输这句，电脑找不到我们创建的工作空间，后续运行会报错！

2. 编译小规范（必记，避免报错）

• 编译前，必须进入 ros2_ws 目录（别在 src 目录里直接编译，会报错）。

• 第一次编译，或改了依赖，输 colcon build --symlink-install（更适合同时有 Python + C++ 包的开发）；只改了一个功能包的代码，输 colcon build --packages-select 功能包名（更快）。

• 编译报错怎么办？先看 build 目录的日志，找“error”；实在解决不了，删除 build、install、log 三个目录，重新编译。

1. 快速回顾（举手回答）：上节课学的4个目录叫什么？src 目录的作用是什么？colcon build 是干嘛的？

1. 功能包是什么（通俗理解）

功能包就是“装特定功能代码的文件夹”，一个功能包负责一个核心功能（比如控制机械臂、识别物料），每个功能包可以单独编译、单独调试，和同学分工合作时，每人负责一个功能包，互不干扰。

例子：智能分拣项目，分成3个功能包，分工更清晰：

• 机械臂控制包（greensort_arm）：专门管机械臂抓取、回零；
• 视觉识别包（greensort_vision）：专门识别苹果品级、定位坐标；
• 分拣协调包（greensort_coordinator）：专门做决策，指挥机械臂和 AGV 配合工作。

2. 一步步创建功能包（跟着老师操作，抄好指令）

1. 步骤1：进入 src 目录（必须在这里创建，否则创建失败）
   指令：cd ~/ros2_ws/src

2. 步骤2：创建功能包（核心指令，记牢！）
   C++ 功能包（ament_cmake）：

   ros2 pkg create greensort_coordinator --build-type ament_cmake --dependencies rclcpp std_msgs
   

Python 功能包（ament_python）：

bash ros2 pkg create greensort_vision --build-type ament_python --dependencies rclpy sensor_msgs

逐字解释（不用记原理，记用法）：

• greensort_coordinator / greensort_vision：功能包名字（建议大家项目包加统一前缀，比如 greensort_）；
• --build-type：构建类型，C++ 常用 ament_cmake，Python 常用 ament_python；
• --dependencies：写你确实要用到的依赖，漏了会编译失败（多写会拖慢编译）；
• 命名规范（重点！）：全小写+下划线，不能有大写、空格、特殊符号。

3. 步骤3：查看功能包结构（创建成功后，src 目录会多一个文件夹）
   重点看这些文件（不用背，能认得出来就行）：

• C++ 包：CMakeLists.txt（编译规则）+ package.xml（依赖清单）；
• Python 包：setup.py / setup.cfg（安装入口）+ package.xml（依赖清单）。

3. package.xml 配置要点（看懂就行，不用自己写）

package.xml 就像功能包的“身份证”，里面写着功能包的名字、版本、需要的依赖，电脑编译时会先看这个文件，所以配置要规范。

• 核心标签（老师会标注在文档里，大家抄下来）：

• <name>：功能包名字（和创建时一致，不能改）；

• <version>：版本号（比如 0.0.0，不用管，默认就行）；

• <depend>：依赖（每个依赖写一行，比如 <depend>rclcpp</depend>，缺了会报错）；

• <buildtool_depend>：构建工具（写 ament_cmake，必须有）。

• 配置小规范（记好，避免报错）：

• 需要什么依赖，就加什么，别多写（多写会让编译变慢）；

• 别漏写依赖，漏了会编译失败；

• 老师会发 AI 生成的规范文档，大家直接参考，不用自己写。

4. 功能包编译与运行（简单了解，后续实操）

1. 编译：回到 ros2_ws 目录，输 colcon build --packages-select greensort_coordinator（只编译这一个包，速度快）；

2. 激活环境：输 source install/setup.bash（注意：colcon build 后生成的是 install 目录，建议 source install）；

3. 运行：输 ros2 run greensort_coordinator coordinator_node（运行包里的节点）；

4. 小提醒：运行前必须激活环境，不然电脑找不到功能包；每个功能包的节点名要唯一。

5. Python 与 C++ 功能包的标准项目结构（学生必须会辨认）

1. C++ 功能包（ament_cmake）常见结构：

greensort_coordinator/
├── CMakeLists.txt
├── package.xml
├── include/
│   └── greensort_coordinator/
│       └── *.hpp
├── src/
│   ├── coordinator_node.cpp
│   └── *.cpp
├── launch/
│   └── *.launch.py
└── config/
    └── *.yaml

2. Python 功能包（ament_python）常见结构：

greensort_vision/
├── package.xml
├── setup.py
├── setup.cfg
├── resource/
│   └── greensort_vision
├── greensort_vision/
│   ├── __init__.py
│   ├── apple_detection_node.py
│   └── *.py
├── launch/
│   └── *.launch.py
└── test/
    └── test_*.py

3. 自定义接口包（msg/srv/action）常见结构（对应 HLD 的 greensort_msgs）：

greensort_msgs/
├── CMakeLists.txt
├── package.xml
├── msg/
│   └── DetectionResult.msg
├── srv/
│   └── ProcessSingle.srv
└── action/
    └── *.action

1. 案例参考：智能分拣项目的功能包划分（深度对齐 HLD 设计）

核心原则：采用“分层解耦”架构，将硬件驱动、业务逻辑、消息定义分离。参考《绿色食品智能分拣系统详细设计》，我们推荐以下划分方案：

• 核心包1：分拣协调包（greensort_coordinator）
  功能：系统的“大脑”，运行 coordinator_node 状态机。负责接收视觉检测结果（/detection/result），调度机械臂（/arm/pick_and_place）和 AGV（/agv/navigate_to）。
  依赖：rclcpp, greensort_msgs, std_msgs

• 核心包2：视觉识别包（greensort_vision）
  功能：系统的“眼睛”，运行 apple_detection_node。负责读取相机图像，进行 AI 推理（判断果径、着色、瑕疵），发布检测结果。
  依赖：rclcpp, sensor_msgs, cv_bridge, greensort_msgs

• 核心包3：机械臂控制包（greensort_arm）
  功能：系统的“手臂”，运行 arm_control_node。封装 MoveIt2 接口，提供抓取和回零位的 Service 服务，不处理复杂业务逻辑。
  依赖：rclcpp, moveit_ros_planning_interface, greensort_msgs

• 基础包4：自定义消息包（greensort_msgs）
  功能：系统的“语言”，定义通用的接口文件。如 DetectionResult.msg（检测结果）、ProcessSingle.srv（抓取指令）。
  依赖：rosidl_default_generators, std_msgs, geometry_msgs

关键要点：每个包只做一件事，依赖清晰。特别是 greensort_msgs，让所有包都能“听懂”同一种语言。

2. 小组任务：规划自己的功能包

结合你们小组的自选题项目，一起讨论，规划2-3个核心功能包，填写下面的内容（老师会发规划表）：

1. 功能包1：名字（符合命名规范）+ 负责的功能 + 需要的依赖（参考案例）；

2. 功能包2：名字 + 负责的功能 + 需要的依赖；

3. 功能包3（可选）：名字 + 负责的功能 + 需要的依赖。

要求：名字符合规范、每个包职责明确、不用多写依赖，结合自己的项目来，别照搬案例。

提示：AI 会给大家推荐划分方案，大家可以参考，但要结合自己的项目修改。

这些规矩是行业里的标准，不管是小组项目，还是以后工作，都要遵守，记好3点就行：

1. 命名规范（必记，避免出错）：

• 工作空间、功能包：全小写+下划线（比如 ros2_ws、greensort_coordinator）；
• 节点、话题、服务：全小写+下划线（比如 coordinator_node、detection/result）；
• 文件名：全小写+下划线，后缀正确（比如 arm_control.cpp、vision_detection.py）。

2. 目录组织（看懂就行，后续实操）：

• 功能包里面，按“源码（src）、头文件（include/功能包名）、配置文件（config）、启动文件（launch）”分类放文件；
• 一个文件别写太多代码，按功能分开写，方便查看。

3. 代码注释（养成习惯）：

• 写函数时，备注一下这个函数是干嘛的、需要什么参数；
• 复杂代码块，备注一下逻辑；
• 写类时，备注一下这个类的功能。

1. 小知识：现在国产 AI 大模型（比如字节跳动 Seed、百度文心一言），可以帮我们生成 ROS2 代码、推荐功能包划分方案、排查编译错误，大大节省开发时间，这是我们国产技术的进步。

2. 职业习惯：规范开发不只是“规矩”，更是一种职业素养。以后做机器人开发相关工作，严谨的命名、清晰的目录、完整的注释，能让你和同事协作更高效，项目更容易落地，这是很重要的能力。

3. 小鼓励：大家要养成规范开发的习惯，借助 AI 工具提升自己，把小组项目做好，为以后的学习和工作打下基础。