ROS2 Foxy YOLOv11 纯视觉 Python 3.8

Auth CNB Blog

让 G1 看见世界,走向目标,伸出双手。

项目介绍

⚡ 快速启动(Web 控制面板,推荐)

# 一次性环境(首次)
python3 -m venv ~/g1act_venv --system-site-packages
source ~/g1act_venv/bin/activate
cd ~/g1act_ws
pip install -r requirements.txt
colcon build --packages-select g1_yolo_nav_py
. install/setup.bash
# 每次启动
source ~/g1act_venv/bin/activate
cd ~/g1act_ws && . install/setup.bash
ros2 run g1_yolo_nav_py web_panel

ros2 run g1_yolo_nav_py web_panel --ros-args -p use_direct_camera:=true
# 直连 D455 + 内置 YOLO 推理,零外部节点

Web 面板功能模块

本地开发预览(无需 ROS2)

cd src/web_frontend
pip install flask pillow
python dev_server.py # 浏览器 http://localhost:8080

项目结构

g1act_ws/
├── README.md # 项目说明(中文)
├── README.en.md # 项目说明(英文)
├── requirements.txt # Python 依赖
├── src/
│ ├── web_frontend/ # Web 前端(HTML/CSS/JS + dev server)
│ │ ├── index.html # 主页面(7 个视图)
│ │ ├── css/style.css # 样式表
│ │ ├── js/app.js # 前端逻辑
│ │ └── dev_server.py # Mock 后端(无 ROS2 依赖)
│ ├── g1_yolo_nav_py/ # 主 ROS2 包
│ │ ├── setup.py # 包设置
│ │ ├── config/
│ │ │ └── arm_poses.json # 手臂姿态配置文件
│ │ ├── launch/ # ROS2 启动文件
│ │ │ ├── grasp_task.launch.py
│ │ │ └── yolo_nav.launch.py
│ │ ├── arm/ # 手臂控制(独立子进程,DDS 隔离)
│ │ │ ├── arm_common.py # 关节常量 + 基类
│ │ │ ├── arm_debug.py # 关节调试子进程(stdin JSON,23 DoF)
│ │ │ ├── armup.py # 抓取动作
│ │ │ ├── armdown.py # 放下动作
│ │ │ ├── leg_squat.py # 下肢蹲下(低层 DDS)
│ │ │ └── leg_stand.py # 下肢站起(低层 DDS)
│ │ └── g1_yolo_nav_py/ # Python 节点模块
│ │ ├── web_panel.py # Web 面板节点 ★ 推荐入口
│ │ ├── control_panel.py # tkinter 控制面板(旧版)
│ │ ├── yolo_detector.py # YOLO 检测
│ │ ├── yaw_align.py # 步进式偏航对齐
│ │ ├── loco_forward.py # 前进 + 深度停止
│ │ ├── grasp_task.py # 终端抓取任务
│ │ ├── rgbd_capture.py # RGBD 数据采集
│ │ ├── spatial_target.py # 2D→3D 空间投影
│ │ ├── _grasp_state.py # 抓取状态机 Mixin
│ │ └── _dds_compat.py # DDS 兼容层
│ └── base/ # 参考包
│ ├── ctrl_keyboard/ # Loco API 参考
│ └── g1_description/ # URDF 模型

更新代码

cd ~/g1act_ws/manact_ws
git pull
colcon build

每次启动

cd ~/g1act_ws/manact_ws
source ~/g1act_venv/bin/activate
. install/setup.bash

快速开始

环境搭建(首次必做)

# 1) 创建虚拟环境(允许访问系统已安装的 ROS2 / unitree_sdk2py)
python3 -m venv ~/g1act_venv --system-site-packages
# 2) 激活虚拟环境
source ~/g1act_venv/bin/activate
# 3) 安装项目依赖
cd ~/g1act_ws/manact_ws
pip install -r requirements.txt
# 4) 编译 ROS2 工作空间
colcon build

# --- 每次启动项目 ---
source ~/g1act_venv/bin/activate
cd ~/g1act_ws
. install/setup.bash

仅测试 YOLO 目标检测

# 1. 启动 D455 相机(终端 1)
ros2 launch realsense2_camera rs_launch.py camera_namespace:=robot1 camera_name:=D455_1
# 2. 编译并启动 YOLO 检测节点(终端 2)
source ~/g1act_venv/bin/activate
colcon build --packages-select g1_yolo_nav_py && . install/setup.bash
ros2 run g1_yolo_nav_py yolo_detector
# 3. 启动可视化节点(终端 3)
ros2 run g1_yolo_nav_py detection_visualizer
# 4. 查看标注图像(终端 4)
ros2 topic echo /g1/vision/detections

# 指定检测目标为 person
ros2 run g1_yolo_nav_py yolo_detector --ros-args -p target_classes:='["person"]'
# 指定自定义模型路径
ros2 run g1_yolo_nav_py yolo_detector --ros-args -p model_path:=/path/to/model.pt

分开调试:目标对齐 vs 运动控制

调试目标对齐(yaw_align)

# 终端 1:相机
ros2 launch realsense2_camera rs_launch.py \
 camera_namespace:=robot1 camera_name:=D455_1
# 终端 2:YOLO 检测
ros2 run g1_yolo_nav_py yolo_detector
# 终端 3:偏航对齐(Loco API SET_VELOCITY)
ros2 run g1_yolo_nav_py yaw_align
# 终端 4(可选):可视化
ros2 run g1_yolo_nav_py detection_visualizer

# 每步旋转更大 — 增大步进速度或持续时间
ros2 run g1_yolo_nav_py yaw_align --ros-args \
 -p step_yaw_speed:=0.5 -p step_duration:=0.4
# 相机更新太慢 — 增加等待时间
ros2 run g1_yolo_nav_py yaw_align --ros-args -p camera_settle_time:=8.0
# 对齐精度不够 — 缩小居中容差
ros2 run g1_yolo_nav_py yaw_align --ros-args -p center_tolerance:=0.05

调试运动控制(loco_forward)

# 终端 1~3:同上(相机 + YOLO + yaw_align)
# 终端 4:前进控制(Loco API SET_VELOCITY)
ros2 run g1_yolo_nav_py loco_forward

# 首次调试用低速度确保安全
ros2 run g1_yolo_nav_py loco_forward --ros-args -p forward_speed:=0.15
# 调整停止距离(离目标更近才停下)
ros2 run g1_yolo_nav_py loco_forward --ros-args -p stop_distance:=0.3
# 关闭深度距离判断,只用 bbox 占比
ros2 run g1_yolo_nav_py loco_forward --ros-args -p use_depth_distance:=false

联合运行

# 方式 A:手动分别启动(推荐调试,方便看各自日志)
# 终端 1: 相机
# 终端 2: ros2 run g1_yolo_nav_py yolo_detector
# 终端 3: ros2 run g1_yolo_nav_py yaw_align
# 终端 4: ros2 run g1_yolo_nav_py loco_forward
# 方式 B:launch 一键启动
ros2 launch g1_yolo_nav_py yolo_nav.launch.py enable_approach:=true

Web 控制面板(推荐)

# 启动(首次需 pip install flask pillow)
ros2 run g1_yolo_nav_py web_panel
# 浏览器打开 http://<机器人IP>:8080

节点管理

完整 API

GET / → 主页
GET /stream/raw → MJPEG 原始视频流
GET /stream/detection → MJPEG 检测标注流
GET /api/state → 全局状态轮询
GET /api/config → 读取热更新配置
POST /api/config → 批量热更新
POST /api/cmd/manual → 手动遥控
POST /api/cmd/stop → 急停
POST /api/cmd/search → 搜索
POST /api/cmd/grab → 抓取
POST /api/cmd/putdown → 放下
POST /api/cmd/turn_putdown → 右转 90° 放下
POST /api/cmd/left_putdown → 左移放下
POST /api/cmd/auto_execute → 一键执行全自动流水线
POST /api/cmd/auto_stop → 停止一键执行流水线
GET /api/cmd/auto_status → 流水线状态
POST /api/arm_debug/start → 启动上肢调试子进程
POST /api/arm_debug/stop → 停止上肢调试
POST /api/arm_debug/send → 发送目标角度
GET /api/arm_debug/status → 调试进程状态
GET /api/arm_debug/presets → 获取预设姿态
GET /api/arm_poses → 读取姿态配置
POST /api/arm_poses → 保存姿态配置
POST /api/arm_poses/run/<name> → 执行 armup/armdown 序列
GET /api/arm_poses/run/status → 序列执行状态
POST /api/process/<n>/start → 启动子进程
POST /api/process/<n>/stop → 停止子进程
GET /api/process/<n>/status → 进程状态 + 日志
POST /api/process/<n>/params → 更新进程参数

系统设置(4 个分组)

自定义参数(启动时固定)

# 自定义端口
ros2 run g1_yolo_nav_py web_panel --ros-args -p http_port:=9090
# 自定义目标类别 + 视频流质量
ros2 run g1_yolo_nav_py web_panel --ros-args \
 -p target_class_id:=bottle \
 -p stream_quality:=50
# 改图像话题(如果命名空间不同)
ros2 run g1_yolo_nav_py web_panel --ros-args \
 -p image_topic:=/camera/color/image_raw

tkinter 控制面板(旧版本,可选)

IDLE → [搜索] → SEARCHING(旋转找目标)
 ↓ 目标出现
 ALIGNING(步进式偏航对齐)
 ↓ 居中稳定
 APPROACHING(Loco API 前进)
 ↓ 深度距离 ≤ 0.5m(或 bbox 占比 ≥ 0.45)
 GRABBING(执行 armup.py)
 ↓ 抓取完成
 MENU(可放下/右转放下)
 ↓ 放下完成
 IDLE

# 终端 1:YOLO 检测
ros2 run g1_yolo_nav_py yolo_detector
# 终端 2:控制面板
ros2 run g1_yolo_nav_py control_panel

抓取任务(一键全流程)

# 终端 1:相机
ros2 launch realsense2_camera rs_launch.py \
 camera_namespace:=robot1 camera_name:=D455_1 align_depth.enable:=true
# 终端 2:YOLO 检测
ros2 run g1_yolo_nav_py yolo_detector
# 终端 3:抓取任务(Loco API 模式,无需 DDS)
ros2 run g1_yolo_nav_py grasp_task

==================================================
G1 抓取任务启动(Loco API 模式)
目标类别: chair
armup: ~/g1act_ws/manact_ws/src/g1_yolo_nav_py/arm/armup.py
armdown: ~/g1act_ws/manact_ws/src/g1_yolo_nav_py/arm/armdown.py
==================================================
[SEARCHING] 旋转搜索目标...
[检测] 识别到目标: chair, 置信度=95%, u=0.32
[状态] SEARCHING → ALIGNING: 目标已找到
[对齐] 一步: u=0.320, 误差=-0.180, 旋转≈+5.2°, 等待5.0s...
[对齐] 等待结束,重新检测: u=0.480
[状态] ALIGNING → APPROACHING: 目标已居中
[状态] APPROACHING → GRABBING: 深度距离=0.48m <= 0.50m
[抓取] 执行 armup.py ...
[抓取] armup.py 执行完成

========================================
 G1 抓取任务 — 操作菜单
========================================
 1. 放下目标物
 2. 右转放下目标物
 3. 自定义控制(输入 xyz)
 4. 退出
========================================
请选择 [1-4]:

# 检测瓶子、降低速度
ros2 run g1_yolo_nav_py grasp_task --ros-args \
 -p target_class_id:=bottle \
 -p forward_speed:=0.15
# 自定义 arm 脚本目录
ros2 run g1_yolo_nav_py grasp_task --ros-args \
 -p arm_script_dir:=/home/unitree/my_arm_scripts

RGBD 数据采集

# 相机启动时需开启深度对齐
ros2 launch realsense2_camera rs_launch.py \
 camera_namespace:=robot1 camera_name:=D455_1 align_depth.enable:=true
# 运行采集(默认每 5s 一帧,持续 60s)
ros2 run g1_yolo_nav_py rgbd_capture
# 自定义参数
ros2 run g1_yolo_nav_py rgbd_capture --ros-args \
 -p interval_sec:=2.0 -p duration_sec:=30.0

运动控制方式

SET_FSM_ID(DAMP=1) → SET_FSM_ID(STAND_UP=4) → SET_FSM_ID(START=500) → SET_FSM_ID(WALK_RUN=801) → SET_BALANCE_MODE(CONTINUOUS_GAIT=1)

调试指南

1. 检查话题连通性

# 检查相机是否发布图像
ros2 topic hz /D455_1/color/image_raw
# 检查深度图是否发布
ros2 topic hz /D455_1/depth/image_rect_raw
# 检查 YOLO 检测结果
ros2 topic echo /g1/vision/detections --once
# 检查运动控制话题订阅者
ros2 topic info /api/sport/request

2. 相机启动(含深度)

# 必须启用深度对齐
ros2 launch realsense2_camera rs_launch.py \
 camera_namespace:=robot1 camera_name:=D455_1 align_depth.enable:=true

3. 验证深度距离

# 单独测试深度图是否正常(应输出 16UC1 或 32FC1 编码)
ros2 topic echo /D455_1/depth/image_rect_raw --once | head -5
# 用 loco_forward 观察距离日志
ros2 run g1_yolo_nav_py loco_forward --ros-args -p forward_speed:=0.0
# forward_speed:=0.0 使机器人不移动,仅观察深度距离日志

4. 关闭深度距离(仅用 bbox)

# 如果深度相机不可用,可关闭深度距离判断
ros2 run g1_yolo_nav_py grasp_task --ros-args -p use_depth_distance:=false

5. 常见问题

6. 分步调试流程

Step 1: 相机 → 确认 /D455_1/color/image_raw 有数据
Step 2: YOLO → 确认 /g1/vision/detections 有检测结果
Step 3: 深度图 → 确认 /D455_1/depth/image_rect_raw 有数据
Step 4: yaw_align → 确认步进式对齐正常(观察日志)
Step 5: loco_forward → forward_speed:=0.0 观察深度距离
Step 6: loco_forward → 正常速度前进,确认到达停止
Step 7: grasp_task → 完整流程测试