🤖 ROS2 零基础全攻略
UR5e 油罐车阀门自动对位项目 — 从完全不懂到能自己改代码
0. 欢迎:这个页面怎么用
你好!如果你对 ROS2 完全不熟悉,这个页面就是为你写的。
📖 阅读方式:
左边是目录,点击可以跳到任何一章。每章都是从最基础的概念开始,用生活比喻解释,然后给出可以复制粘贴到终端运行的命令。
🟢 绿色框 = 小贴士 / 好习惯 | 🟠 橙色框 = 常见错误 / 注意事项
▶ 折叠区 = 点击展开更多细节。不想看太深可以跳过。
代码块以 $ 开头的是终端命令(直接复制粘贴跑),没有 $ 的是代码内容。
1. ROS2 是什么?
一句话
ROS2 (Robot Operating System 2) = 机器人软件的"Android 系统"。
就像 Android 帮手机 App 管理摄像头、触摸屏、WiFi 一样,ROS2 帮机械臂管理关节、相机、规划算法、通信。
为什么需要 ROS2?
假如你要写一个机械臂程序,你需要:
- 读相机图像 → 需要相机驱动
- 识别物体位置 → 需要 AI 模型
- 规划机械臂怎么动 → 需要运动学算法
- 让电机转 → 需要电机控制协议
不用 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 模型 |
真正的大脑还是你写的 Python 代码(比如我们的 valve_scan.py)。
2. 你的开发环境
你现在有什么?
你在用 VMware 虚拟机,里面跑 Ubuntu 22.04,上面装了 ROS2 Humble。
用一个比喻:
- Windows 笔记本 = 你的房子
- VMware = 房子里的一个房间
- Ubuntu 虚拟机 = 这个房间里的工作台
- 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
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 个节点在同时工作的动画:
📝 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)。发布者不关心谁在听。
📝 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)。期间客户端必须等待。
📝 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) — 长任务+进度反馈 🎯
动作 = 服务 + 持续反馈 + 可取消。适合耗时长、需要进度的任务(比如机械臂运动到目标)。
📝 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 | ⚙️ 配置项 | 节点内读写 | ❌ | ❌ | 运行时调参数 |
• 订阅话题 /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/ 里可运行的程序。下面是这个过程的动画:
📝 命令行: 编译的完整流程
# ===== 最常用的三种 ===== # 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 4 | 4 核并行 | 内存够时加速 (8GB≤4) |
--cmake-args -DCMAKE_BUILD_TYPE=Release | 优化编译 | 正式发布时 |
📝 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++ 包 (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 (开始扫描)
8. Gazebo — 3D 物理仿真器
Gazebo 是什么?
Gazebo 是一个虚拟的机器人实验室。它有重力、碰撞、摩擦力、光照。你可以在里面"虚拟"放一台机械臂,测试它能不能动、会不会撞到自己。
打个比方:Gazebo = 飞行模拟器。你在电脑上开飞机,但物理规律跟真的一样。
Gazebo 里有什么?
场景容器
机械臂、油罐车、桌面
相机、深度、IMU
碰撞检测、重力、关节
Gazebo 的操作(在窗口里用鼠标)
| 操作 | 效果 |
|---|---|
| 鼠标左键拖拽 | 旋转视角 |
| 鼠标滚轮 | 缩放 |
| 鼠标中键拖拽 | 平移视角 |
| 右键 + 拖 | 绕目标旋转 |
| 双击模型 | 聚焦到该模型 |
Gazebo 的两个进程
| 进程 | 做什么 | 命令行 |
|---|---|---|
gzserver | 物理引擎 (重力、碰撞、关节)。没有画面,但机械臂真实在动 | gzserver 世界文件.world |
gzclient | 3D 渲染窗口。让你"看见"机械臂。不跑也不影响物理 | gzclient |
9. RViz — 3D 可视化工具
RViz 是什么?
RViz 是 ROS2 的"监控屏"。它不仿真物理,只是把数据画出来给你看。
| Gazebo | RViz |
|---|---|
| 物理仿真器:有力、有碰撞 | 可视化工具:只看,不碰 |
| 机械臂"真实"在动 | 机械臂"显示"在动 |
| 可以跑物理实验 | 可以看数据、调参数 |
| 关掉 → 物理停了 | 关掉 → 不影响仿真 |
RViz 里能看什么?
| Display 插件 | 显示什么 |
|---|---|
RobotModel | 机械臂 3D 模型 (跟着 /joint_states 实时动) |
TF | 彩色坐标轴 (base_link, tool0, camera_link 等) |
Image | 相机画面 (可以订阅 /camera/rgb/image_raw) |
MotionPlanning | MoveIt 交互面板 (拖动末端 → Plan & Execute) |
Grid | 参考网格 (1m×1m 格子) |
RViz 的拖动控制怎么用?
在 RViz 左下角 MotionPlanning 面板里:
- 看机械臂末端有没有彩色圆球/箭头(交互 marker)
- 如果没有 → 在 Displays 栏里展开 MotionPlanning → 把 Query Goal State 的 Interactive Marker 打勾
- 鼠标拖拽彩色圆球到新位置
- 点 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 (上下) | 说明 |
|---|---|---|---|---|
| world / base_link | — | — | — | 机械臂看到的"绝对位置" |
| tool0 (末端) | — | — | — | 末端"自己视角"看阀门在哪 |
💡 关键洞察:同一个阀门点,在不同坐标系下数值完全不同。但它们描述的是同一个物理位置。TF 就是做这个换算的。
⭐ 试试切到 tool0 视角,转关节——你会发现整个世界都在绕末端转!这就是"以末端为原点看世界"。
我们项目里的关键 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
12. YOLOv8 — 视觉识别 [动画+代码]
🎬 YOLOv8 检测动画
下面模拟 YOLOv8 检测阀门的过程——输入图像 → 神经网络推理 → 输出边界框+类别+置信度:
📝 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)
• yolov8n.pt (nano, 6MB) → 最快, CPU 也能跑, 我们用这个
• yolov8s.pt (small, 22MB) → 更准, 需要好 CPU
• yolov8m/l/x.pt → 最准但最慢, 需要 GPU
12.5 参数 (Parameter) — 运行时可调的配置项 [动画+代码]
⚙️ 参数是什么?
参数 = 节点的"设置项"。就像手机里的亮度滑块——不重启就能调。
在 ROS2 里,参数让你在不改代码、不重新编译的情况下调整节点行为。
🎬 参数通信动画
📝 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 的关键参数
| 参数名 | 类型 | 默认值 | 作用 |
|---|---|---|---|
confidence | float | 0.35 | YOLOv8 检测置信度阈值 |
scan_speed | float | 0.06 | 360°扫描时关节转速(rad/周期) |
center_tolerance_px | int | 70 | 检测框居中容差(像素) |
min_confirmed_frames | int | 3 | 连续确认帧数才算检测到 |
servo_gain | float | 0.75 | 伺服增益(距离→速度比例) |
servo_max_speed | float | 0.12 | 伺服最大速度(m/s) |
servo_target_offset | float | 0.06 | 停在阀门前方距离(m) |
target_frame | str | "base_link" | 坐标变换目标系 |
sim_fallback_enabled | bool | True | 扫描失败用预设位置 |
ros2 param set /valve_scan confidence 0.5 立即生效。调好了再 ros2 param dump /valve_scan 导出到 yaml 固化。正确:
ros2 param set /node speed 0.8 (数字)错误:
ros2 param set /node speed "0.8" (字符串)13. 项目实战:逐行解析 valve_scan.py
这是整个项目的核心 (942 行)。下面按执行顺序而不是代码顺序讲解。
▶ 第 1 步:节点启动 __init__()
节点启动时做的事:
- 声明参数 (declare_parameter) — 所有可调参数集中在这里
- 加载 YOLO 模型 — 失败返回 None (后续用 HSV 回退)
- 创建话题订阅 — 听 /camera/rgb/image_raw、/joint_states 等
- 创建话题发布 — 发 /joint_trajectory (关节命令)、/servo_node/delta_twist_cmds (速度命令)
- 创建服务客户端 — 切换控制器、启动 Servo
- 启动定时器 — 每 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
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
🎉 恭喜!你现在已经了解了这个项目的方方面面。
遇到问题 → 回到这个页面搜关键词 → 对应章节有解释。
想深入了解某个部分 → 展开折叠区看详细代码。