伯克利开源低成本的示教神器GELLO-5.数据收集操作说明
本文档详细介绍如何使用 GELLO 开源项目进行遥操作数据收集，适用于机器人模仿学习（Imitation Learning）任务。
前置准备
硬件要求
● GELLO 设备: 已组装完成的 GELLO 遥操作主臂
● 机械臂: 支持的机械臂（Franka Panda/FR3、UR、xArm、I2RT YAM 等）
● 摄像头（可选）: 用于视觉观测的腕部/基座摄像头
● 计算机: Ubuntu 20.04/22.04 系统
软件依赖
确保已完成以下安装，具体参考，安装过的可以跳过这一步：
# 1. 克隆仓库
git clone https://github.com/wuphilipp/gello_software.git
cd gello_software
# 2. 安装 uv（如果未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 3. 创建虚拟环境
uv venv --python 3.11
source .venv/bin/activate
# 4. 安装依赖
git submodule init
git submodule update
uv pip install -r requirements.txt
uv pip install -e .
uv pip install -e third_party/DynamixelSDK/python
环境配置
1. 配置 GELLO 设备
1.1 校准关节偏移量
在使用 GELLO 之前，需要先校准关节偏移量（joint offsets）：
# 示例：Franka FER (Panda) 机械臂
python scripts/gello_get_offset.py \ --start-joints 0 0 0 -1.57 0 1.57 0 \ --joint-signs 1 1 1 1 1 -1 1 \ --port /dev/serial/by-id/usb-FTDI_USB__-__Serial_Converter_FT7WBG6
# 示例：UR 机械臂
python scripts/gello_get_offset.py \ --start-joints 0 -1.57 1.57 -1.57 -1.57 0 \ --joint-signs 1 1 -1 1 1 1 \ --port /dev/serial/by-id/usb-FTDI_USB__-__Serial_Converter_FT7WBG6
# 示例：I2RT YAM
python scripts/gello_get_offset.py \ --start-joints 0 0 0 0 0 0 \ --joint-signs 1 -1 -1 -1 1 1 \ --port /dev/serial/by-id/usb-FTDI_USB__-__Serial_Converter_FTAAMLV6-if00-port0
参数说明：
- --start-joints: GELLO 和机械臂的初始对齐角度（弧度）
- --joint-signs: 关节方向符号（根据机械臂类型选择）
- --port: GELLO 设备的串口路径
常见机械臂的 joint signs：
机械臂 Joint Signs
UR 1 1 -1 1 1 1
Panda 1 -1 1 1 1 -1 1
xArm 1 1 1 1 1 1 1
YAM 1 -1 -1 -1 1 1
1.2 添加配置到代码
将生成的 joint offsets 添加到 gello/agents/gello_agent.py 的 PORT_CONFIG_MAP 中。
数据收集流程
方法一：使用 YAML 配置启动（推荐）
适用于 I2RT YAM 机械臂：
# 启动数据收集（单臂）
python experiments/launch_yaml.py \ --left-config-path configs/yam_auto_generated.yaml \ --use-save-interface
# 启动数据收集（双臂）
python experiments/launch_yaml.py \ --left-config-path configs/gello_1.yaml \ --right-config-path configs/gello_2.yaml \ --use-save-interface
方法二：手动分步启动
适用于其他机械臂或非 YAM 配置：
步骤 1：启动机器人节点
# 真实硬件
python experiments/launch_nodes.py --robot <ur|panda|xarm>
# 仿真环境
python experiments/launch_nodes.py --robot <sim_ur|sim_panda|sim_xarm>
步骤 2：启动 GELLO 控制器并启用数据保存
python experiments/run_env.py \ --agent=gello \ --use-save-interface \ --data-dir ~/bc_data \ --start-joints 0 -1.57 1.57 -1.57 -1.57 0
参数说明：
- --agent: 代理类型（gello、quest、spacemouse 等）
- --use-save-interface: 启用数据保存接口
- --data-dir: 数据保存目录（默认 ~/bc_data）
- --start-joints: 初始关节位置（弧度）
- --gello-port: 指定 GELLO 串口（可选）
- --bimanual: 启用双臂模式
操作控制
启动成功后，终端会显示：
Save interface enabled. Use keyboard controls: S: Start recording Q: Stop recording
键盘控制说明：
按键 功能
S 开始录制数据
Q 停止录制并退出
数据收集步骤
1. 启动系统：执行上述启动命令
2. 移动到起始位置：GELLO 会自动与机械臂对齐
3. 开始录制：按下键盘S键
4. 执行遥操作：通过 GELLO 手柄控制机械臂完成任务
5. 停止录制：按下键盘Q键
6. 重复：重复步骤 3-5 收集更多演示数据
数据处理与转换
原始数据位置
收集的原始数据保存在：
<data_dir>/<agent_name>/<MMDD_HHMMSS>/ ├── 000000.pkl ├── 000001.pkl ├── 000002.pkl └── ...
转换为训练格式
使用 demo_to_gdict.py 将原始数据转换为 HDF5 格式：
python gello/data_utils/demo_to_gdict.py \
--source-dir ~/bc_data/gello
输出结构：
~/bc_data/gello/_conv/multiview/ ├── train/ │ └── none/ │ ├── traj_0.h5 │ ├── traj_1.h5 │ └── ... ├── val/ │ └── none/ │ └── ... └── vis/ # 可视化文件 ├── rgb/ │ ├── traj_0_rgb_wrist.mp4 │ ├── traj_0_rgb_base.mp4 │ └── _all_rgb.mp4 ├── depth/ │ └── ... ├── state/ │ └── traj_0_states.png └── action/ └── traj_0_actions.png
处理脚本功能
demo_to_gdict.py 自动完成以下操作：
1. 数据归一化：计算动作的 scale factor 和 bias factor
2. 格式转换：将.pkl转换为.h5（HDF5）格式
3. 生成可视化：- RGB 视频（腕部 + 基座视角）- 深度图视频- 关节状态图- 动作分布图
4. 数据集划分：自动划分为训练集（90%）和验证集（10%）
数据格式说明
原始数据格式（.pkl）
每个 .pkl 文件包含一个时间步的数据：
{
"joint_positions": np.ndarray, # 机械臂关节位置（弧度）
"joint_velocities": np.ndarray, # 关节速度
"control": np.ndarray, # 控制指令（目标关节位置）
"timestamp": float, # 时间戳
# 如果配置了摄像头：
"rgb": np.ndarray, # RGB 图像 [N_cam, H, W, 3]
"depth": np.ndarray, # 深度图 [N_cam, H, W]
}转换后数据格式（.h5）
HDF5 文件使用 GDict 格式：
{
"traj_<id>": {
"obs": {
"state": np.ndarray, # 状态向量
"rgb": np.ndarray, # RGB 图像 [T, N_cam, C, H, W]
"depth": np.ndarray # 深度图 [T, N_cam, H, W]
},
"actions": np.ndarray, # 动作序列 [T, action_dim]
"dones": np.ndarray, # 结束标志
"episode_dones": np.ndarray # 回合结束标志
}
}动作归一化
转换脚本会自动计算归一化参数：
# 归一化公式
normalized_action = (action - bias_factor) / scale_factor
# 输出结果示例
scale_factor = np.array([...]) # 每个维度的缩放因子
bias_factor = np.array([...]) # 每个维度的偏置
常见问题排查
1. 串口权限问题
问题：无法访问 GELLO 串口设备
解决：
# 将当前用户添加到 dialout 组
sudo usermod -aG dialout $USER
# 重新登录或重启系统
2. 找不到 GELLO 设备
问题：No gello port found
解决：
# 列出所有串口设备
ls -la /dev/serial/by-id/
# 手动指定串口
python experiments/run_env.py \ --agent=gello \ --use-save-interface \ --gello-port /dev/serial/by-id/usb-FTDI_USB__-__Serial_Converter_FT7WBG6
3. 关节方向错误
问题：某些关节运动方向与预期相反
解决：
- 修改配置文件中的 joint_signs，将对应关节的符号取反
- 或者物理上反转舵机的安装方向
4. 数据保存失败
问题：按 S 键后没有数据保存
解决：
1. 确认终端处于激活状态（点击终端窗口）
2. 检查 --data-dir 路径是否有写入权限
3. 查看终端输出是否有错误信息
5. 数据转换失败
问题：demo_to_gdict.py 报错
解决：
1. 确保数据目录包含有效的 .pkl 文件
2. 检查是否安装了 mediapy：
uv pip install mediapy
3. 确保有足够的磁盘空间
完整示例流程
# 1. 进入项目目录
cd gello_software
source .venv/bin/activate
# 2. 校准 GELLO（首次使用）
python scripts/gello_get_offset.py \ --start-joints 0 0 0 -1.57 0 1.57 0 \ --joint-signs 1 1 1 1 1 -1 1 \ --port /dev/serial/by-id/usb-FTDI_USB__-__Serial_Converter_FT7WBG6
# 3. 启动机器人节点（终端 1）
python experiments/launch_nodes.py --robot panda
# 4. 启动数据收集（终端 2）
python experiments/run_env.py \ --agent=gello \ --use-save-interface \ --data-dir ~/my_robot_data \ --start-joints 0 -1.57 1.57 -1.57 -1.57 0
# 5. 按 S 开始录制，执行遥操作任务，按 Q 停止
# 6. 处理收集的数据
python gello/data_utils/demo_to_gdict.py \ --source-dir ~/my_robot_data/gello
# 7. 查看可视化结果
ls ~/my_robot_data/gello/_conv/multiview/vis/