🤖 ROS2 零基础全攻略

🤖 ROS2 零基础全攻略

UR5e 油罐车阀门自动对位项目 — 从完全不懂到能自己改代码

0. 欢迎:这个页面怎么用

你好!如果你对 ROS2 完全不熟悉,这个页面就是为你写的。

📖 阅读方式:

左边是目录,点击可以跳到任何一章。每章都是从最基础的概念开始,用生活比喻解释,然后给出可以复制粘贴到终端运行的命令。

🟢 绿色框 = 小贴士 / 好习惯 | 🟠 橙色框 = 常见错误 / 注意事项

▶ 折叠区 = 点击展开更多细节。不想看太深可以跳过。

代码块以 $ 开头的是终端命令(直接复制粘贴跑),没有 $ 的是代码内容。

💡 建议:把 VM 终端打开放在旁边,边看边敲命令。动手比光看快 10 倍。
🦾
配套专题:URDF/xacro 零基础全攻略
看不懂机械臂描述文件?这篇专题逐行拆解 orion_6r_industrial_arm.urdf.xacro,含可动机械臂演示
前往专题 →

1. ROS2 是什么?

一句话

ROS2 (Robot Operating System 2) = 机器人软件的"Android 系统"。

就像 Android 帮手机 App 管理摄像头、触摸屏、WiFi 一样,ROS2 帮机械臂管理关节、相机、规划算法、通信。

为什么需要 ROS2?

假如你要写一个机械臂程序,你需要:

不用 ROS2:你要自己写每一个部分的代码、自己处理各种硬件的兼容性。

用 ROS2:这些功能都被做成了"积木块"(叫做包 package),你只要把它们拼起来。

我们项目里用了哪些 ROS2 的"积木块"?

需求ROS2 提供的"积木"我们做什么
相机驱动gazebo_ros_camera (仿真相机插件)配个 SDF 文件指定分辨率/FOV
机械臂模型ur_description (UR5e URDF)加一个固定相机 link
关节控制ros2_control (控制器框架)配 yaml 文件, 切换控制器
运动规划MoveIt2 (IK + 路径规划)调它的 Python API
视觉识别YOLOv8 (深度学习)写检测逻辑 + 3D反投影
3D 仿真Gazebo (物理引擎)画油罐车 + 阀门 SDF 模型
💡 关键理解:ROS2 不帮你写算法,它帮你搭架子——让相机和算法之间能通信、让算法和机械臂之间能通信。
真正的大脑还是你写的 Python 代码(比如我们的 valve_scan.py)。

2. 你的开发环境

你现在有什么?

你在用 VMware 虚拟机,里面跑 Ubuntu 22.04,上面装了 ROS2 Humble。

用一个比喻:

重要的路径 (记下来,经常要用)

路径里面是什么什么时候去
~/ros2_ws/你的工作空间根目录编译、启动 launch、git 操作
~/ros2_ws/src/源代码都在这里改代码、写新包
~/ros2_ws/src/ur_fuelcap/我们自己的包改核心逻辑 (valve_scan.py 等)
~/ros2_ws/build/编译中间产物 (自动生成)不需要进去
~/ros2_ws/install/编译好的最终产物source 它之后才能 ros2 run
/opt/ros/humble/ROS2 系统本身 (apt 装的)不需要进去,但要 source

每次开新终端,第一件事

# 这两条命令 "激活" ROS2 环境 和 你的工作空间
# 不跑这两条, ros2 / colcon 命令都不认识
$ source /opt/ros/humble/setup.bash
$ source ~/ros2_ws/install/setup.bash
💡 偷懒技巧:把上面两条加到 ~/.bashrc 文件末尾,以后开终端自动执行。
$ echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
$ echo "source ~/ros2_ws/install/setup.bash" >> ~/.bashrc
⚠️ 常见错误:忘了 source 就敲 ros2 命令,终端说"找不到命令"。跑上面两条 source 就行。

3. 工作空间 (workspace) — 你的"项目文件夹"

什么是工作空间?

工作空间就是 你的项目的根目录。所有代码、编译结果、配置文件都在里面。

打个比方:工作空间就是一栋楼的建筑工地。src/ 是蓝图室 (源代码),build/ 是施工区 (编译),install/ 是建好的房间 (可运行)。

工作空间的目录结构

~/ros2_ws/                     ← 工地大门 (所有 colcon 命令在这里跑)
├── src/                       ← 蓝图室: 所有包的源代码
│   ├── ur_fuelcap/            ← 我们写的包 (核心)
│   ├── universal_robots/      ← 下载的 UR 驱动
│   ├── ros2_control/          ← 下载的控制器框架
│   └── ...                    ← 更多下载的依赖
├── build/                     ← 施工区: 编译中间文件 (不要手动改)
├── install/                   ← 成品区: source 这里即可运行
├── log/                       ← 日志: 编译和运行日志
└── .gitignore                 ← 告诉 git 忽略 build/ install/

工作空间怎么创建的?

# 第 1 步: 新建空目录
$ mkdir -p ~/ros2_ws/src

# 第 2 步: 把源码放到 src/ 里 (克隆或者自己写)
$ cd ~/ros2_ws/src
$ git clone 某个仓库

# 第 3 步: 编译 (回到工作空间根目录)
$ cd ~/ros2_ws
$ colcon build --symlink-install

# 第 4 步: source 安装空间, 让系统认识你的包
$ source ~/ros2_ws/install/setup.bash
⚠️ 关键:colcon build 一定要在 ~/ros2_ws/ (工作空间根目录) 跑,不要在 src/ 里跑。

4. 包 (package) — 最小的功能单元

什么是包?

包 = ROS2 世界里最小的功能单元。一个包就是一个目录,里面有代码、配置、模型等,一起完成某个功能。

打个比方:一个包 = 一个乐高套装。UR5e 驱动是一个套装,MoveIt 规划是一个套装,我们的 valve_scan 也是一个套装。

一个包里面有什么?(以 ur_fuelcap 为例)

文件/目录必须?里面写的什么
package.xml✅ 必须包的身份证:名字、版本、依赖哪些其他包
CMakeLists.txt✅ (C++包)编译规则:哪些文件要安装到哪里
launch/选填启动文件 (.launch.py):一键启动多个节点
nodes/选填Python 节点代码:业务逻辑
urdf/选填机器人模型描述文件 → 看不懂?读这篇专题
worlds/选填Gazebo 仿真世界描述文件
config/选填参数配置文件 (yaml)

项目里的包分类

我们写的 ur_fuelcap — 项目核心(9 个文件,自己写的)

我们写的 custom_arm — 自定义机械臂模板(练习用)

下载的 ur_description, ur_moveit_config, ur_simulation_gazebo 等 — UR 官方提供

下载的 ros2_control, ros2_controllers 等 — ROS2 官方控制框架

系统自带 moveit_core, rviz2, gazebo_ros 等 — apt 装的二进制包,不需要编译

▶ 怎么看一个包提供了什么功能?
# 列出所有已安装的包
$ ros2 pkg list

# 看某个包的详细信息 (路径、依赖)
$ ros2 pkg xml ur_fuelcap

# 看包里有哪些可执行文件 (能 ros2 run 的)
$ ros2 pkg executables ur_fuelcap

5. 节点·话题·服务·动作 — ROS2 四大通信方式 [动画+代码]

ROS2 节点之间有 4 种通信方式。下面每个都有动画演示 + 可复制的 Python 代码。

① 节点 (Node) — 干活的"工人" 🤖

每个节点是一个独立的进程。下面是 3 个节点在同时工作的动画:

同时运行的多个节点 (各自独立工作) 📷 camera_node 拍图, 每秒15帧 🧠 valve_scan 检测阀门+对位 🎮 controller 驱动机械臂关节 ↑ 每个节点独立运行, 互不阻塞 就像餐厅: 厨师/服务员/收银员同时干活, 各司其职 💡 但它们怎么互相通信? → 用下面三种方式

📝 Python: 创建一个节点

# my_first_node.py — 最简单的 ROS2 节点
import rclpy
from rclpy.node import Node

class MyFirstNode(Node):
    def __init__(self):
        # 给节点起个名字 (ros2 node list 能看到)
        super().__init__('my_first_node')
        # 每秒打印一次
        self.timer = self.create_timer(1.0, self.tick)
        self.get_logger().info('节点启动了!')

    def tick(self):
        self.get_logger().info('滴答 — 我还活着')

def main():
    rclpy.init()                    # 初始化 ROS2
    node = MyFirstNode()             # 创建节点
    rclpy.spin(node)                 # 阻塞运行(处理回调)
    node.destroy_node()
    rclpy.shutdown()

if __name__ == '__main__':
    main()

运行: ros2 run 包名 my_first_node.py → 另开终端 ros2 node list 能看到 /my_first_node

② 话题 (Topic) — 微信群广播 📢

一个节点发布(Publish)消息到话题,其他节点订阅(Subscribe)。发布者不关心谁在听。

话题通信: 一对多广播 (发布者不知道有谁在听) 📷 Publisher create_publisher() /joint_states 话题名 🧠 valve_scan 订阅 📊 RViz 也订阅 💡 一个发布者 → 多个订阅者同时收到(广播)

📝 Python: 发布者 + 订阅者

# === 发布者: 每0.5秒发一次关节角度 ===
import rclpy
from rclpy.node import Node
from sensor_msgs.msg import JointState

class JointPublisher(Node):
    def __init__(self):
        super().__init__('joint_publisher')
        # 创建发布者: 话题名 + 消息类型 + 队列大小
        self.pub = self.create_publisher(JointState, '/joint_states', 10)
        self.timer = self.create_timer(0.5, self.publish_joint)
        self.angle = 0.0

    def publish_joint(self):
        msg = JointState()
        msg.name = ['shoulder_pan_joint']
        msg.position = [self.angle]
        self.pub.publish(msg)          # ← 发出去!
        self.angle += 0.1
        self.get_logger().info('发了角度: {:.2f}'.format(self.angle))


# === 订阅者: 收到消息就调回调 ===
class JointSubscriber(Node):
    def __init__(self):
        super().__init__('joint_subscriber')
        # 创建订阅者: 话题名 + 消息类型 + 回调函数 + 队列
        self.create_subscription(
            JointState, '/joint_states', self.on_joint, 10)

    def on_joint(self, msg):           # ← 收到消息自动调这个
        self.get_logger().info('收到: {} = {:.2f}'.format(
            msg.name[0], msg.position[0]))

③ 服务 (Service) — 打电话一问一答 📞

客户端发请求(Request) → 服务端处理后返回响应(Response)。期间客户端必须等待。

服务通信: 同步一问一答 (必须等回复) Client valve_scan Server controller_mgr 请求→ ←响应 服务名: /controller_manager/switch_controller 💡 客户端发请求后阻塞, 直到拿到响应才继续

📝 Python: 服务端 + 客户端

# === 服务端: 提供加法计算服务 ===
from example_interfaces.srv import AddTwoInts

class AddServer(Node):
    def __init__(self):
        super().__init__('add_server')
        # 创建服务: 服务名 + 回调
        self.create_service(AddTwoInts, 'add_two_ints', self.handle_add)

    def handle_add(self, request, response):
        response.sum = request.a + request.b   # 处理请求
        self.get_logger().info('{} + {} = {}'.format(
            request.a, request.b, response.sum))
        return response                  # 返回响应


# === 客户端: 调用服务 ===
class AddClient(Node):
    def __init__(self):
        super().__init__('add_client')
        self.cli = self.create_client(AddTwoInts, 'add_two_ints')
        # 等服务端上线
        while not self.cli.wait_for_service(timeout_sec=1.0):
            self.get_logger().info('等待服务...')

    def call(self, a, b):
        req = AddTwoInts.Request()
        req.a = a
        req.b = b
        future = self.cli.call_async(req)     # 异步发请求
        rclpy.spin_until_future_complete(self, future)  # 等结果
        return future.result().sum

④ 动作 (Action) — 长任务+进度反馈 🎯

动作 = 服务 + 持续反馈 + 可取消。适合耗时长、需要进度的任务(比如机械臂运动到目标)。

动作通信: 发目标 → 持续收反馈 → 收结果 (可中途取消) Action Client valve_scan Action Server move_group ①发目标(Goal) ②持续反馈(Feedback) "已完成 30%... 50%... 80%..." ③最终结果(Result) "到达目标! ✅" ④可随时取消(Cancel)

📝 Python: 动作客户端 (我们项目实际用的)

# 调用 MoveIt 的 /move_action 动作 — 让机械臂运动到目标
from rclpy.action import ActionClient
from moveit_msgs.action import MoveGroup

class ArmMover(Node):
    def __init__(self):
        super().__init__('arm_mover')
        # 创建动作客户端: 节点 + 动作类型 + 动作名
        self.client = ActionClient(self, MoveGroup, '/move_action')

    def move_to(self, target_pose):
        # ① 发送目标
        goal = MoveGroup.Goal()
        goal.request.goal = target_pose
        self.client.wait_for_server()
        future = self.client.send_goal_async(
            goal, feedback_callback=self.on_feedback)

    def on_feedback(self, feedback):
        # ② 持续收到进度反馈 (每秒多次)
        pct = feedback.feedback.percent_complete
        self.get_logger().info('进度: {:.0%}'.format(pct))

    def on_result(self, future):
        # ③ 最终结果
        result = future.result().result
        self.get_logger().info('运动完成! ✅')

📊 四种通信方式对比

方式比喻方向需要回复?有进度?用在哪
话题 Topic📢 微信群单向(发布→订阅)❌ 不需要❌传感器数据流(相机/关节)
服务 Service📞 打电话双向(请求→响应)✅ 必须❌切换模式/查询状态
动作 Action🎯 外卖订单双向+持续反馈✅ 必须✅ 有机械臂运动/导航
参数 Parameter⚙️ 配置项节点内读写❌❌运行时调参数
💡 选择口诀:持续数据流 → 话题 | 一次性问答 → 服务 | 长任务要看进度 → 动作 | 调参 → 参数
⚠️ 我们项目的实际用法:valve_scan 用了全部 4 种:
• 订阅话题 /camera/image_raw 收相机图
• 发布话题 /joint_trajectory 发关节命令
• 调服务 /switch_controller 切换控制器
• (间接通过 MoveIt)调动作 /move_action 规划运动
• 声明参数 confidence/scan_speed 等可调阈值
▶ 实战命令: 查看这些通信
# 看所有节点
$ ros2 node list

# 看所有话题
$ ros2 topic list

# 看所有服务
$ ros2 service list

# 看所有动作
$ ros2 action list

# 偷听话题数据
$ ros2 topic echo /joint_states

# 调用服务
$ ros2 service call /add_two_ints example_interfaces/srv/AddTwoInts "{a: 3, b: 5}"

6. 编译 (colcon build) — 把代码变成能跑的程序 [动画+代码]

🎬 编译流程动画

colcon 把 src/ 里的源代码 → 编译 → 生成 install/ 里可运行的程序。下面是这个过程的动画:

colcon build 流程: src → build → install 📁 src/ 源代码 package.xml CMakeLists.txt nodes/*.py launch/*.py urdf/*.xacro worlds/*.world meshes/*.stl colcon 解析依赖 🔨 build/ 编译中间产物 CMake 配置 make 编译 ⚠️ 不要手动改 自动生成 install 拷贝/链接 📦 install/ 可运行产物 share/ launch/ worlds/ lib/ 节点可执行 ← source 这个! 💡 source install/setup.bash 后, ros2 run/launch 就能找到你的包

📝 命令行: 编译的完整流程

# ===== 最常用的三种 =====

# 1. 只编译我们自己的包 (最快, 日常开发用)
$ cd ~/ros2_ws
$ colcon build --packages-select ur_fuelcap --symlink-install

# 2. 编译所有包 (慢, 第一次搭建环境时用)
$ colcon build --symlink-install --parallel-workers 4

# 3. 跳过某些包 (比如测试失败的不编)
$ colcon build --packages-skip tricycle_controller

# 4. 编译后必须 source (否则 ros2 找不到新包)
$ source ~/ros2_ws/install/setup.bash

📊 每个 flag 是什么意思?

flag作用什么时候用
--packages-select 包名只编译指定的包 (快)日常开发, 改了一个包
--packages-skip 包名跳过指定的包某个包编不过, 先跳过
--symlink-install符号链接代替拷贝永远加! 改 Python 不用重编
--parallel-workers 44 核并行内存够时加速 (8GB≤4)
--cmake-args -DCMAKE_BUILD_TYPE=Release优化编译正式发布时
⚠️ --symlink-install 是救命功能:加了这个参数后,你改 Python 文件(.py)、launch 文件、xacro 文件都不需要重新 colcon build。只有改 C++ 文件和 CMakeLists.txt 才需要重编。

📝 package.xml — 包的身份证 (必学)

每个包必须有 package.xml。它告诉 colcon:"这个包叫什么、依赖哪些其他包"。

<?xml version="1.0"?>
<package format="3">
  <name>ur_fuelcap</name>                          <!-- 包名 -->
  <version>0.1.0</version>                        <!-- 版本号 -->
  <description>UR5e 阀门对位系统</description>      <!-- 一句话描述 -->
  <maintainer email="cfs@todo.todo">cfs</maintainer> <!-- 维护者 -->
  <license>Apache-2.0</license>                    <!-- 开源协议 -->

  <!-- 构建工具: C++包用 ament_cmake, Python包用 ament_python -->
  <buildtool_depend>ament_cmake</buildtool_depend>

  <!-- 运行时依赖: 这个包需要哪些其他 ROS2 包 -->
  <exec_depend>rclpy</exec_depend>                 <!-- ROS2 Python 库 -->
  <exec_depend>sensor_msgs</exec_depend>            <!-- 图像/关节消息类型 -->
  <exec_depend>gazebo_ros</exec_depend>             <!-- Gazebo 仿真 -->
  <exec_depend>xacro</exec_depend>                   <!-- URDF 模板引擎 -->

  <export><build_type>ament_cmake</build_type></export>
</package>

📝 CMakeLists.txt — 编译规则 (必学)

cmake_minimum_required(VERSION 3.8)
project(ur_fuelcap)                                # 项目名(同 package.xml)

find_package(ament_cmake REQUIRED)                 # 找构建工具

# 把这些目录安装到 install/share/ur_fuelcap/ 下
# 这样 launch 文件里 get_package_share_directory('ur_fuelcap') 能找到
install(DIRECTORY launch worlds urdf config
  DESTINATION share/${PROJECT_NAME}
)

# 安装 Python 节点到 install/lib/ur_fuelcap/
# 这样 ros2 run ur_fuelcap valve_scan.py 能找到
install(PROGRAMS nodes/valve_scan.py
  DESTINATION lib/${PROJECT_NAME}
)

ament_package()                                    # 声明这是一个 ament 包
💡 C++ vs Python 包的区别:
• C++ 包 (ament_cmake): 有 CMakeLists.txt, 编译 .cpp → .so/.可执行文件
• Python 包 (ament_python): 有 setup.py/setup.cfg, 不编译, 直接安装 .py
• 我们的 ur_fuelcap 是 混合包: 用 ament_cmake 但只装 Python 和配置文件
▶ 编译失败了怎么办?

第 1 步:看最后 20 行,找 "error" 关键词。

$ colcon build --packages-select ur_fuelcap 2>&1 | tail -30

第 2 步:如果是"找不到某个包"→ 缺依赖,用 apt 装或 rosdep。

# 自动装依赖
$ rosdep install --from-paths src --ignore-src -y --rosdistro humble

第 3 步:如果是"语法错误"→ 去看对应文件的行号。

第 4 步:改完后重新 build (加 --continue-on-error 看全部错误)。

7. 启动 (ros2 launch) — 一键启动整个系统

ros2 run vs ros2 launch

命令作用例子
ros2 run 包名 节点名启动一个节点ros2 run ur_fuelcap valve_scan.py
ros2 launch 包名 launch文件启动一堆节点 (按 launch 文件配置)ros2 launch ur_fuelcap fuelcap_sim.launch.py

打个比方:ros2 run = 手动开一个灯。ros2 launch = 按一个开关,整层楼的灯全亮。

我们的 launch 文件做了什么?

fuelcap_sim.launch.py 启动后发生的事情:

  t=0s:    Gazebo + robot_state_publisher 同时启动
  t=8s:    把 UR5e 模型"放入"Gazebo (spawn)
  t=20s:   激活 3 个控制器
  t=30s:   启动 MoveIt2 move_group
  t=34s:   启动 valve_scan (开始扫描)
💡 为什么要有延时?因为 Gazebo 启动要时间,如果在 Gazebo 还没完全起来时就往里面放机械臂,会失败。

8. Gazebo — 3D 物理仿真器

Gazebo 是什么?

Gazebo 是一个虚拟的机器人实验室。它有重力、碰撞、摩擦力、光照。你可以在里面"虚拟"放一台机械臂,测试它能不能动、会不会撞到自己。

打个比方:Gazebo = 飞行模拟器。你在电脑上开飞机,但物理规律跟真的一样。

Gazebo 里有什么?

世界 (World)
场景容器
→
模型 (Model)
机械臂、油罐车、桌面
→
传感器 (Sensor)
相机、深度、IMU
→
物理引擎 (ODE)
碰撞检测、重力、关节

Gazebo 的操作(在窗口里用鼠标)

操作效果
鼠标左键拖拽旋转视角
鼠标滚轮缩放
鼠标中键拖拽平移视角
右键 + 拖绕目标旋转
双击模型聚焦到该模型

Gazebo 的两个进程

进程做什么命令行
gzserver物理引擎 (重力、碰撞、关节)。没有画面,但机械臂真实在动gzserver 世界文件.world
gzclient3D 渲染窗口。让你"看见"机械臂。不跑也不影响物理gzclient
💡 关键理解:即使你关掉 Gazebo 的窗口 (gzclient),gzserver 还在后台跑,机械臂还在动。相机也能继续出图。所以如果电脑太卡,关掉 Gazebo 窗口不影响仿真。

9. RViz — 3D 可视化工具

RViz 是什么?

RViz 是 ROS2 的"监控屏"。它不仿真物理,只是把数据画出来给你看。

GazeboRViz
物理仿真器:有力、有碰撞可视化工具:只看,不碰
机械臂"真实"在动机械臂"显示"在动
可以跑物理实验可以看数据、调参数
关掉 → 物理停了关掉 → 不影响仿真

RViz 里能看什么?

Display 插件显示什么
RobotModel机械臂 3D 模型 (跟着 /joint_states 实时动)
TF彩色坐标轴 (base_link, tool0, camera_link 等)
Image相机画面 (可以订阅 /camera/rgb/image_raw)
MotionPlanningMoveIt 交互面板 (拖动末端 → Plan & Execute)
Grid参考网格 (1m×1m 格子)

RViz 的拖动控制怎么用?

在 RViz 左下角 MotionPlanning 面板里:

  1. 看机械臂末端有没有彩色圆球/箭头(交互 marker)
  2. 如果没有 → 在 Displays 栏里展开 MotionPlanning → 把 Query Goal State 的 Interactive Marker 打勾
  3. 鼠标拖拽彩色圆球到新位置
  4. 点 Plan(只看规划动画)或 Plan & Execute(真的让 Gazebo 里机械臂动)

但我们的自动化不依赖这个——valve_scan 自己发轨迹,不需要人拖。

10. MoveIt2 — 运动规划引擎

MoveIt2 做什么?

MoveIt2 = 机械臂的"导航系统"。就像 GPS 告诉你从 A 到 B 怎么走,MoveIt2 告诉机械臂"关节怎么转才能让末端到那个位置,而且不撞到自己"。

MoveIt2 提供的三大能力

能力解释比喻
IK (逆运动学)给末端位置 → 算出 6 个关节角度"手指要摸到杯子"→"肩膀转15° 手肘弯30°..."
路径规划从当前姿态到目标姿态,找一条无碰撞的路径导航软件规划路线避开堵车
碰撞检测判断某姿态会不会撞到自己或环境倒车雷达,快撞了报警

MoveIt Servo 是什么?

Servo = MoveIt 的实时控制模式。不像普通的"先规划再执行",Servo 是每秒 50 次读取输入、计算输出。我们的 valve_scan 最后就用 Servo 完成精密逼近。

我们的 move_group 怎么启动的?

fuelcap_sim.launch.py 里这行启动 move_group (MoveIt 的核心节点):
move_group = IncludeLaunchDescription(
    PythonLaunchDescriptionSource(ur_moveit_config/launch/ur_moveit.launch.py)
)

move_group 节点在后台跑,提供 IK 计算、Servo 后端。它不需要 GUI。

11. TF (坐标变换) — 空间里的"地图" [含动画演示]

TF 是什么?

TF = 跟踪所有坐标系之间的位置关系。机械臂有多个 link (底座、大臂、小臂……),每个 link 有自己的坐标系。TF 告诉你"小臂坐标系在底座坐标系里的什么位置"。

打个比方

你拿着手机导航:GPS 告诉你经纬度(世界坐标系),手机告诉你"前方 100 米左转"(手机坐标系)。

TF 做的是:把不同坐标系下的位置换算到同一个坐标系下。

🎮 交互演示:拖动滑块看坐标变换

下方是一个简化的 2D 机械臂(侧视图)。拖动滑块转动关节,观察不同坐标系如何跟着转,以及"阀门点"在各个坐标系下的数值如何变化。

屏幕坐标: 右=+X, 下=+Y (为直观, z 朝上已翻转) ground 🎯 阀门

📊 阀门点的坐标(在不同坐标系下的数值)

坐标系X (左右)Y (前后)Z (上下)说明
world / base_link———机械臂看到的"绝对位置"
tool0 (末端)———末端"自己视角"看阀门在哪

💡 关键洞察:同一个阀门点,在不同坐标系下数值完全不同。但它们描述的是同一个物理位置。TF 就是做这个换算的。

⭐ 试试切到 tool0 视角,转关节——你会发现整个世界都在绕末端转!这就是"以末端为原点看世界"。

💡 核心理解:TF 不是改变物体位置,而是改变"观察的视角"。就像你站在原地转头,世界没动,但你眼里看到的东西位置变了。机械臂的 IK 求解、路径规划,本质都是在不同坐标系之间做这种换算。

我们项目里的关键 TF

world (世界原点)
 └── base_link (机械臂底座)  ← 【主坐标系, 所有3D位置最终都转到这里】
      ├── shoulder_link → upper_arm_link → forearm_link → wrist_1/2/3_link → tool0
      └── base_axis_camera_link → base_axis_camera_optical_frame ← 【相机】

怎么查看 TF?

# 看某两个坐标系之间的变换关系
$ ros2 run tf2_ros tf2_echo base_link tool0

# 生成 TF 树图 (PDF)
$ ros2 run tf2_tools view_frames.py  # 会在当前目录生成 frames.pdf
⚠️ TF 的坑:如果 TF 链断了 (比如 camera_link 没连接到 base_link),反投影出的 3D 点就是错的。valve_scan 里有 try/except TransformException 来处理这个。

12. YOLOv8 — 视觉识别 [动画+代码]

🎬 YOLOv8 检测动画

下面模拟 YOLOv8 检测阀门的过程——输入图像 → 神经网络推理 → 输出边界框+类别+置信度:

YOLOv8 检测流程: 输入图 → CNN推理 → 输出检测结果 📷 输入图像 640×640 RGB predict() 🧠 CNN 神经网络 卷积层提取特征 ✅ 检测结果 类别: valve 置信度: 0.87 框: (52,77,108,153) valve 0.87 输出: [类别名, 置信度, x1, y1, x2, y2] 💡 (x1,y1)=左上角像素, (x2,y2)=右下角像素 只用 1 次前向传播就出结果 → "You Only Look Once"

📝 Python: 完整的 YOLOv8 检测代码 (从零开始)

# === 第 1 步: 安装 ===
# 终端运行: pip3 install ultralytics (会自动装 PyTorch)

# === 第 2 步: 加载模型 ===
from ultralytics import YOLO

# 用预训练模型 (能识别 80 类常见物体: 人/车/瓶子/...)
model = YOLO('yolov8n.pt')       # n=nano(最快最小), 还有 s/m/l/x

# 或者用自训练模型 (比如我们检测阀门)
# model = YOLO('valve_yolov8.pt')

# === 第 3 步: 检测一张图 ===
import cv2
image = cv2.imread('camera_shot.jpg')    # 读图

results = model.predict(
    image,
    imgsz=640,        # 输入尺寸 (越大越准越慢)
    conf=0.35,         # 置信度阈值 (低于此值忽略)
    verbose=False      # 不打印日志
)

# === 第 4 步: 解析检测结果 ===
for result in results:
    for box in result.boxes:
        cls_id = int(box.cls[0])          # 类别 ID (数字)
        cls_name = model.names[cls_id]     # 类别名 ("valve"/"person"/...)
        score = float(box.conf[0])        # 置信度 0~1
        x1, y1, x2, y2 = box.xyxy[0]      # 边界框 [左,上,右,下]

        print(f'{cls_name} ({score:.2f}) at {x1:.0f},{y1:.0f}')

        # 画框 (OpenCV)
        cv2.rectangle(image, (int(x1),int(y1)), (int(x2),int(y2)),
                      (0,255,0), 2)
        cv2.putText(image, f'{cls_name} {score:.2f}',
                    (int(x1), int(y1)-10),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0,255,0), 2)

cv2.imwrite('result.jpg', image)      # 保存带框的图

📝 Python: 在 ROS2 节点里用 YOLOv8 (我们项目的写法)

import rclpy
from rclpy.node import Node
from sensor_msgs.msg import Image
from cv_bridge import CvBridge
from ultralytics import YOLO

class ValveDetector(Node):
    def __init__(self):
        super().__init__('valve_detector')
        self.bridge = CvBridge()
        self.model = YOLO('valve_yolov8.pt')     # 加载模型
        # 订阅相机话题
        self.create_subscription(
            Image, '/camera/rgb/image_raw', self.on_image, 10)

    def on_image(self, msg):
        # ROS Image → OpenCV Mat
        image = self.bridge.imgmsg_to_cv2(msg, 'bgr8')
        # YOLO 检测
        results = self.model.predict(image, conf=0.35, verbose=False)
        # 找阀门
        for box in results[0].boxes:
            cls = self.model.names[int(box.cls[0])]
            if cls == 'valve':
                x1,y1,x2,y2 = box.xyxy[0]
                cx = (x1+x2)/2    # 框中心 X
                cy = (y1+y2)/2    # 框中心 Y
                self.get_logger().info(
                    f'阀门在像素({cx:.0f},{cy:.0f}), 置信度{box.conf[0]:.2f}')

📝 Python: 自训练阀门检测模型

# === 第 1 步: 采集数据 ===
# 在 Gazebo 里截图, 或用相机拍 100-500 张阀门照片
# 放到 dataset/images/ 目录

# === 第 2 步: 标注 (画框) ===
# 用 LabelImg 或 Roboflow 标注, 生成 .txt 标签文件
# 格式: class_id  cx_norm  cy_norm  w_norm  h_norm

# === 第 3 步: 写 data.yaml ===
# valve.yaml:
#   train: dataset/images/train/
#   val: dataset/images/val/
#   nc: 1
#   names: ['valve']

# === 第 4 步: 训练 (一条命令) ===
model = YOLO('yolov8n.pt')
model.train(data='valve.yaml', epochs=100, imgsz=640)
# 训练完生成 runs/detect/train/weights/best.pt

# === 第 5 步: 用训练好的模型 ===
model = YOLO('runs/detect/train/weights/best.pt')

HSV 颜色回退 (无模型时用)

如果没有 YOLOv8 权重文件,valve_scan.py 会自动降级到 HSV 颜色检测:

import cv2, numpy as np

# 把 BGR 转 HSV 色彩空间
hsv = cv2.cvtColor(image, cv2.COLOR_BGR2HSV)

# 黄色的 HSV 范围 (H:18-38, 高饱和度)
lower = np.array([18, 80, 80])
upper = np.array([38, 255, 255])
mask = cv2.inRange(hsv, lower, upper)      # 二值掩码

# 找轮廓
contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
for c in contours:
    if cv2.contourArea(c) > 50:           # 过滤小噪点
        x,y,w,h = cv2.boundingRect(c)     # 边界框
        cv2.rectangle(image,(x,y),(x+w,y+h),(0,255,0),2)
💡 YOLOv8 模型大小选择:
• yolov8n.pt (nano, 6MB) → 最快, CPU 也能跑, 我们用这个
• yolov8s.pt (small, 22MB) → 更准, 需要好 CPU
• yolov8m/l/x.pt → 最准但最慢, 需要 GPU

12.5 参数 (Parameter) — 运行时可调的配置项 [动画+代码]

⚙️ 参数是什么?

参数 = 节点的"设置项"。就像手机里的亮度滑块——不重启就能调。

在 ROS2 里,参数让你在不改代码、不重新编译的情况下调整节点行为。

🎬 参数通信动画

参数: 外部读写节点内部的配置值 🤖 valve_scan 节点 confidence = 0.35 scan_speed = 0.06 servo_gain = 0.75 target_frame = "base_link" 📝 ros2 param set 写入 📖 ros2 param get 读取 🚀 launch 覆盖 💡 参数存在节点内部, 启动时设默认值, 运行中可用命令行动态修改

📝 Python: 声明和使用参数 (节点内部)

import rclpy
from rclpy.node import Node

class MyNode(Node):
    def __init__(self):
        super().__init__('my_node')

        # === 声明参数 (必须先声明才能用) ===
        # 格式: declare_parameter('名字', 默认值)
        # 类型由默认值决定: int / float / str / bool / list
        self.declare_parameter('speed', 0.5)           # float
        self.declare_parameter('joint_name', 'shoulder') # string
        self.declare_parameter('max_iterations', 100)     # int
        self.declare_parameter('debug_mode', False)        # bool
        self.declare_parameter('target_joints', ['j1','j2'])  # list

        # === 读取参数值 ===
        self.speed = self.get_parameter('speed').value
        self.joint = self.get_parameter('joint_name').value
        self.debug = self.get_parameter('debug_mode').value

        self.get_logger().info(f'速度={self.speed}, 关节={self.joint}')

        # === 监听参数变化 (动态生效) ===
        self.add_on_set_parameters_callback(self.on_param_change)

    def on_param_change(self, params):
        # 参数被外部修改时触发
        for p in params:
            if p.name == 'speed':
                self.speed = p.value
                self.get_logger().info(f'速度改为 {self.speed}')
        from rcl_interfaces.msg import SetParametersResult
        return SetParametersResult(successful=True)

📝 命令行: 查看和修改参数

# 查看某节点的所有参数
$ ros2 param list /valve_scan

# 查看某个参数的值
$ ros2 param get /valve_scan confidence

# 运行中动态修改参数 (立即生效!)
$ ros2 param set /valve_scan confidence 0.50

# 启动时通过命令行覆盖参数
$ ros2 run my_pkg my_node --ros-args -p speed:=1.0 -p debug_mode:=true

# 从 yaml 文件批量加载参数
$ ros2 param load /valve_scan params.yaml

# 导出当前参数到 yaml
$ ros2 param dump /valve_scan

📝 launch 文件里设参数

from launch_ros.actions import Node

my_node = Node(
    package='my_pkg',
    executable='my_node',
    parameters=[{
        # 启动时设参数 (覆盖代码里的默认值)
        'speed': 1.2,
        'debug_mode': True,
        # 或者从 yaml 文件加载
    }],
    # 也可以引用 yaml 文件:
    # parameters=[os.path.join(pkg_share, 'config', 'params.yaml')]
)

📝 YAML 参数文件 (批量管理)

# params.yaml — 用文件管理大量参数
valve_scan:
  ros__parameters:
    confidence: 0.35
    scan_speed: 0.06
    servo_gain: 0.75
    servo_target_offset: 0.06
    target_frame: "base_link"
    target_classes: ["valve", "gas_valve", "gas_port"]
    valve_min_x: 0.55
    valve_max_x: 1.15

📊 我们项目 valve_scan.py 的关键参数

参数名类型默认值作用
confidencefloat0.35YOLOv8 检测置信度阈值
scan_speedfloat0.06360°扫描时关节转速(rad/周期)
center_tolerance_pxint70检测框居中容差(像素)
min_confirmed_framesint3连续确认帧数才算检测到
servo_gainfloat0.75伺服增益(距离→速度比例)
servo_max_speedfloat0.12伺服最大速度(m/s)
servo_target_offsetfloat0.06停在阀门前方距离(m)
target_framestr"base_link"坐标变换目标系
sim_fallback_enabledboolTrue扫描失败用预设位置
💡 实战技巧:调参时不用重启节点!终端跑 ros2 param set /valve_scan confidence 0.5 立即生效。调好了再 ros2 param dump /valve_scan 导出到 yaml 固化。
⚠️ 注意:参数类型必须和声明时一致。声明的是 float,set 时传字符串会报错。
正确: ros2 param set /node speed 0.8 (数字)
错误: ros2 param set /node speed "0.8" (字符串)

13. 项目实战:逐行解析 valve_scan.py

这是整个项目的核心 (942 行)。下面按执行顺序而不是代码顺序讲解。

▶ 第 1 步:节点启动 __init__()

节点启动时做的事:

  1. 声明参数 (declare_parameter) — 所有可调参数集中在这里
  2. 加载 YOLO 模型 — 失败返回 None (后续用 HSV 回退)
  3. 创建话题订阅 — 听 /camera/rgb/image_raw、/joint_states 等
  4. 创建话题发布 — 发 /joint_trajectory (关节命令)、/servo_node/delta_twist_cmds (速度命令)
  5. 创建服务客户端 — 切换控制器、启动 Servo
  6. 启动定时器 — 每 250ms 调一次 tick()
▶ 第 2 步:收到图像 → on_image() → detect_valve()
# on_image() 被调用的时机: 每次相机发一帧新图像
def on_image(self, msg):
    image = self.bridge.imgmsg_to_cv2(msg)        # ROS Image → OpenCV Mat
    detection = self.detect_valve(image)           # 调 YOLO 或 HSV
    if detection:
        # 有检测 → 画框 → 判断是否居中 → 计数
        cx = (x1 + x2) / 2                         # 检测框中心横坐标
        if abs(cx - image_w/2) < 70:              # 距图像中心 < 70 像素?
            self.confirmed_frames += 1             # 居中计数 +1
        else:
            self.confirmed_frames = 0              # 不居中 → 清零
▶ 第 3 步:状态机 tick() → scanning

扫描模式下,每 250ms:

# 已经连续 3 帧居中? → 锁定阀门位置
if self.confirmed_frames >= 3:
    point = self.compute_valve_point()   # 计算阀门 3D 位置
    if point is not None:
        self.align_to_valve_point(point) # 进入对位阶段
        return

# 还没找到 → 继续旋转 shoulder_pan
next_pan = self.last_pan_command + 0.06    # 每次转 0.06 rad (≈3.4°)
self.publish_trajectory(...)               # 发关节轨迹
▶ 第 4 步:3D 反投影 point_from_detection()

这是整个项目最核心的算法(约 40 行代码):

输入:  检测框 (x1,y1,x2,y2) + 深度图 + 相机内参 K
输出:  阀门在 base_link 基坐标系下的 (X, Y, Z)

步骤 1: 取检测框中心像素 (u, v)
u = (x1 + x2) / 2
v = (y1 + y2) / 2

步骤 2: 在深度图的 (u,v) 周围 9×9 区域取深度中位数
depth_m = median( depth[v-4:v+5, u-4:u+5] )
  ↑ 取中位数而不是直接取点, 是为了抗单个像素噪声

步骤 3: 用针孔相机模型反投影
X_camera = (u - cx) * depth_m / fx   # fx, cx 从 /camera_info 获取
Y_camera = (v - cy) * depth_m / fy
Z_camera = depth_m

步骤 4: TF 变换 camera → base_link
point_base = tf_buffer.transform(point_camera, 'base_link')
▶ 第 5 步:笛卡尔逼近 servo_to_valve()

每周期 (50Hz):

步骤 1: 查 tool0 当前位置 (通过 TF)
tool_tf = tf_buffer.lookup_transform('base_link', 'tool0', ...)

步骤 2: 算误差
dx = target.x - tool_tf.translation.x
dy = target.y - tool_tf.translation.y
dz = target.z - tool_tf.translation.z
dist = sqrt(dx² + dy² + dz²)

步骤 3: 到位判定
if dist < 0.025:  # 2.5cm 内 = 到位
    state = 'connected'  ✅

步骤 4: 发速度 (P 控制 + 限幅)
speed = min(0.12, 0.75 * dist)  # 最大 12cm/s, 增益 0.75
vx = dx / dist * speed
vy = dy / dist * speed
vz = dz / dist * speed
publish_servo_twist(vx, vy, vz)  # 只平动, 不转角度

14. 调试命令大全

以下命令都在终端里跑,可以帮你快速定位问题。

▶ 🔍 系统状态
# 看当前有哪些节点在运行 (列表为空 = launch 没起来)
$ ros2 node list

# 看某个节点的详细信息
$ ros2 node info /valve_scan

# 看所有话题
$ ros2 topic list

# 看话题的类型和发布者
$ ros2 topic info /camera/rgb/image_raw
▶ 📊 数据检查
# 实时看关节角度 (传感器真在发数据吗?)
$ ros2 topic echo /joint_states

# 只看一帧 (--once)
$ ros2 topic echo /joint_states --once

# 看相机是否真的在出图 (看 header 信息, 不打印像素)
$ ros2 topic echo /camera/rgb/image_raw --once --no-arr | head -10

# 看话题发布频率 (应该有数值)
$ ros2 topic hz /joint_states
▶ 🛑 清理
# 杀所有 Gazebo 进程
$ pkill -9 -f gzserver
$ pkill -9 -f gzclient

# 杀所有 ROS2 launch 残留
$ pkill -9 -f "ros2 launch"

# 一次性暴力清理 (所有可能残留的)
$ pkill -9 -f gzserver; pkill -9 -f gzclient; pkill -9 -f move_group; pkill -9 -f controller_manager; pkill -9 -f robot_state_publisher; pkill -9 -f rviz2
▶ 📝 日志
# 找最新一次 launch 的日志目录
$ ls -td ~/.ros/log/*/ | head -1

# 看 launch 的过程 (所有节点启动/死亡记录)
$ cat ~/.ros/log/最新目录/launch.log | grep -E "process|ERROR"

# 看 valve_scan 节点的输出 (INFO/WARN/ERROR)
$ cat ~/.ros/log/最新目录/valve_scan*.log

15. Git 版本管理

Git 是什么?

Git = "时光机"+"网盘"。时光机 = 随时回到以前的版本。网盘 = 把代码同步到 Gitee/GitHub。

最常用的 5 条命令

# 1. 看改了哪些文件
$ cd ~/ros2_ws
$ git status

# 2. 把所有改动加入暂存区
$ git add -A

# 3. 提交 (在本地创建一个 "快照")
$ git commit -m "描述你改了什么"

# 4. 推送到远程 (Gitee)
$ git push

# 5. 看提交历史
$ git log --oneline

常见场景

# "我改坏了, 想回到上次提交的状态"
$ git checkout -f           # 丢弃所有未提交的改动 (小心!)

# "我想看某个文件以前是什么样"
$ git log --oneline src/ur_fuelcap/nodes/valve_scan.py   # 看历史
$ git show 提交号:src/ur_fuelcap/nodes/valve_scan.py     # 看某版本内容

# "远程仓库改了, 我本地想同步"
$ git pull
⚠️ 别提交 build/ 和 install/! 这两个目录已经被 .gitignore 排除了 (我们配好了)。它们加起来几 GB,提交只会浪费空间。

16. 动手练习 (边做边学)

练习 1:确认环境正常

$ source /opt/ros/humble/setup.bash
$ source ~/ros2_ws/install/setup.bash
$ ros2 pkg list | grep ur_fuelcap   # 应该输出 ur_fuelcap
$ ros2 topic list                   # (如果没有 launch 在跑, 会报错, 正常)

练习 2:启动仿真,观察系统

$ ros2 launch ur_fuelcap fuelcap_sim.launch.py
# 等 40 秒...
# 开另一个终端:
$ ros2 node list                    # 看看有哪些节点在运行
$ ros2 topic list | head -20        # 看看有哪些话题
$ ros2 topic echo /joint_states --once | head -15  # 看关节角度

练习 3:改自定义机械臂参数

$ cd ~/ros2_ws
$ vim src/custom_arm/urdf/custom_arm.urdf.xacro
# 找到 upper_arm_length 那一行, 把 0.35 改成 0.55
# 保存退出 (:wq)
$ ros2 launch custom_arm display.launch.py   # 看机械臂变长了没

练习 4:Git 版本控制

$ cd ~/ros2_ws
$ git status                       # 看到 custom_arm 是新的
$ git add -A
$ git commit -m "练习: 改了自定义机械臂上臂长度"
$ git log --oneline

🎉 恭喜!你现在已经了解了这个项目的方方面面。

遇到问题 → 回到这个页面搜关键词 → 对应章节有解释。

想深入了解某个部分 → 展开折叠区看详细代码。

🤖 问 DeepSeek

🔑 配置 DeepSeek API

💡 获取 Key: platform.deepseek.com/api_keys
Key 只存在浏览器 localStorage,不会上传任何地方。
404 错误? 把 endpoint 留空 (用默认)。