智能佳机器人知识社区

伯克利开源低成本的示教神器GELLO-1.1.Gello-UR5硬件组装说明

Wed, 29 Jul 2026 23:00:00 +0800

物料清单（UR5）

序号	描述	数量	链接
1	DYNAMIXEL XL330-M288-T	6	https://item.jd.com/10026901343226.html#switch-sku
2	DYNAMIXEL XL330-M077-T	1	https://item.jd.com/10152431689447.html#switch-sku
3	U2D2	1	https://item.jd.com/10152431689448.html#switch-sku
4	U2D2 Power Hub Board Set	1
5	Power Supply	1
6	Longer Cables 加长数据线	2	https://item.jd.com/10021472385991.html
7	Rubber Bands 橡皮筋	1
8	Springs	1

3D打印部件：

请访问gello_mechanical的github仓库获取用于打印的STL文件。（https://github.com/wuphilipp/gello_mechanical）需打印部件：

机器人抓取器部件

您选择的机器人部件

下面我们展示了每个机器人的3D打印部件。建议的3D打印方向如下所示。注意：大多数部件建议使用支撑。

3D打印部件（夹爪，机器人共用）

handle.stl	trigger.stl

3D打印部件（UR5）

base.stl	L1.stl	L2.stl

L3.stl	L4.stl	L5.stl

确保你面前摆放着所有必要的零件。你还需要一把小十字头螺丝刀。

3D 打印结构件

舵机

螺丝

288-T舵机用于手臂

077-T舵机用于夹持器

Dynamixels附带的螺丝有短款和长款两种：

短款螺丝用于安装在电机轴头上

长款螺丝用于将3D打印部件安装在舵机底座上

GELLO的组装十分简便

电机结构通过长螺钉固定在3D打印部件上

电机舵盘则通过短螺钉固定在3D打印部件上

最终组装的GELLO应该看起来像这样：

伯克利开源低成本的示教神器GELLO-2.软件安装

Wed, 29 Jul 2026 22:30:00 +0800

GELLO 是一个通用、低成本且直观的机器人机械臂远程操作框架。

采购

项目网站（查看GELLO 的论文和其他资源）：https://wuphilipp.github.io/gello_site/

软件库

硬件库：访问 GELLO 硬件仓库，获取 STL 文件和硬件说明

ROS 2 支持

软件安装

mkdir ~/projects

cd ~/projects

git clone https://ghfast.top/https://github.com/wuphilipp/gello_software.git

cd gello_software

虚拟环境（推荐）

首先，如果没有UV，请先安装：

curl -LsSf https://astral.sh/uv/install.sh | sh

创建并激活虚拟环境：

uv venv --python 3.11

source .venv/bin/activate

git submodule init

git submodule update

如果访问github遇到网络问题的：可以跳过git submodule init和git submodule update参考如下操作

cd /home/robot/projects/gello_software/third_party

rm -rf DynamixelSDK mujoco_menagerie

git clone https://ghfast.top/https://github.com/ROBOTIS-GIT/DynamixelSDK.git

git clone https://ghfast.top/https://github.com/google-deepmind/mujoco_menagerie.git

cd /home/robot/projects

uv pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

uv pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

uv pip install -e third_party/DynamixelSDK/python

uv pip install rich -i https://pypi.tuna.tsinghua.edu.cn/simple

伯克利开源低成本的示教神器GELLO-3.1.遥操UR5

Wed, 29 Jul 2026 22:00:00 +0800

关节信号参考值

机器人类型	关节信号参考	自由度
UR	1 1 -1 1 1 1	6
Panda	1 -1 1 1 1 -1 1	7
FR3	1 1 1 1 1 -1 1	7
xArm7	1 1 1 1 1 1 1	7
YAM	1 -1 -1 -1 1 1	6

cd ~/projects/gello_software/

source .venv/bin/activate

ls /dev/serial/by-id

运行指令控制（复制自己的设备号，替换/dev/serial/by-id/后面部分）

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

校准操作（仿真模拟测试）

对于仿真模拟测试（复制自己的设备号，替换/dev/serial/by-id/后面部分）

python3 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_FTA4B4D5-if00-port0

替换~/projects/gello_software/gello/agents/gello_agent.py代码

PORT_CONFIG_MAP部分对应joint_offsets和gripper_config部分，并核对joint_signs：

python3 experiments/launch_nodes.py --robot sim_ur

重新启动一个终端

再次将主臂处于和仿真臂一致的姿势（重点：主臂一定要虚拟的从臂姿势要一致，根据自己仿真机械臂的姿势来调整主臂初始位置，否则无法遥操作或者运动的不一致）

cd ~/projects/gello_software/

source .venv/bin/activate

python3 experiments/run_env.py --agent=gello

对于实物（参考）

手动gello_agent设置

将 GELLO 和机械臂设置为已知的匹配配置（见下图），然后运行偏移检测脚本。

伯克利开源低成本的示教神器GELLO-3.2.遥操 Franka FR3 / Panda

Wed, 29 Jul 2026 21:30:00 +0800

手动gello_agent设置

将 GELLO 和机械臂设置为已知的匹配配置（见下图），然后运行偏移检测脚本。

机器人类型	关节信号参考	自由度
UR	1 1 -1 1 1 1	6
Panda	1 -1 1 1 1 -1 1	7
FR3	1 1 1 1 1 -1 1	7
xArm7	1 1 1 1 1 1	7
YAM	1 -1 -1 -1 1 1	6

cd ~/projects/gello_software/

source .venv/bin/activate

ls /dev/serial/by-id

运行指令控制

仿真模拟测试

注意：
仿真的初始校准需要按照下图姿势进行校准和开始遥操

python scripts/gello_get_offset.py \
    --start-joints 0 0 0 0 0 0 0 \
    --joint-signs 1 1 1 1 1 -1 1 \
    --port /dev/serial/by-id/usb-FTDI_USB__-__Serial_Converter_FTB1V2HJ-if00-port0

运行上述代码将运行结果替换到gello/agents/gello_agent.py

模拟测试

python3 experiments/launch_nodes.py --robot sim_panda

注意：对于FR3要更改相应代码：https://github.com/wuphilipp/gello_software/blob/main/experiments/launch_nodes.py

elif args.robot == "sim_fr3":
        from gello.robots.sim_robot import MujocoRobotServer

        MENAGERIE_ROOT: Path = (
            Path(__file__).parent.parent / "third_party" / "mujoco_menagerie"
        )
        xml = MENAGERIE_ROOT / "franka_fr3" / "fr3.xml"
        gripper_xml = None
        server = MujocoRobotServer(
            xml_path=xml, gripper_xml_path=gripper_xml, port=port, host=args.hostname
        )
        server.serve()

python3 experiments/launch_nodes.py --robot sim_fr3

cd ~/projects/gello_software/

source .venv/bin/activate

python3 experiments/run_env.py --agent=gello

伯克利开源低成本的示教神器GELLO-3.3.遥操xArm7机器人

Wed, 29 Jul 2026 21:00:00 +0800

cd ~/projects/gello_software/

source .venv/bin/activate

ls /dev/serial/by-id

机器人类型	关节信号参考	自由度
UR	1 1 -1 1 1 1	6
Panda	1 -1 1 1 1 -1 1	7
FR3	1 1 1 1 1 -1 1	7
xArm7	1 1 1 1 1 1 1	7
YAM	1 -1 -1 -1 1 1	6

python3 scripts/gello_get_offset.py \
   --start-joints 0 0 0 0 0 0 0 \
    --joint-signs 1 1 1 1 1 1 1 \
    --port /dev/serial/by-id/复制你的设备串口号

python3 experiments/launch_nodes.py --robot sim_xarm

重新打开一个终端

cd ~/projects/gello_software/

source .venv/bin/activate

python3 experiments/run_env.py --agent=gello

伯克利开源低成本的示教神器GELLO-3.4.遥操I2RT-YAM机械臂

Wed, 29 Jul 2026 20:30:00 +0800

1. 系统概述

GELLO（Generalized End-to-End Learning for Locomation and manipulation Operations）是伯克利开源的低成本遥操作工具，可用于控制多种机械臂进行数据收集和遥控操作。本手册针对YAM机械臂的GELLO适配进行详细说明。

GELLO支持多种主流机械臂平台，包括UR、Panda、FR3、xArm7等。YAM机械臂作为6自由度协作机械臂，通过GELLO可实现直观的演示教学和遥控操作。

1.1 适用范围说明

本文档主要针对MuJoCo仿真环境下的YAM机械臂遥操作进行说明。 MuJoCo是一款高性能物理仿真引擎，可在无真实硬件的情况下进行算法验证和演示教学。

同时，本文档中的配置方法同样适用于真实YAM机械臂。使用真实机械臂时，只需将启动命令中的sim_yam改为yam，并确保机械臂与控制计算机正确连接即可。

提示：建议首次使用先在MuJoCo仿真环境中进行练习，熟悉操作后再连接真实机械臂。

1.2 相关资源链接

本文档需配合以下资源使用：

·GELLO软件安装教程：包含完整的软件安装、环境配置、依赖包安装步骤

http://rosrobot.cn/?id=657

·GELLO-YAM配置指南：YAM机械臂的关节配置和偏移量校准说明

http://rosrobot.cn/?id=709

·GELLO项目官网：论文、演示视频和其他资源

https://wuphilipp.github.io/gello_site/

·软件库GitHub：源代码和更新

https://github.com/wuphilipp/gello_software

·硬件库GitHub：STL文件和硬件说明

https://github.com/wuphilipp/gello_mechanical

2.1 硬件要求

·YAM 6自由度协作机械臂（或mujoco仿真环境） × 1

·GELLO-YAMn臂× 1

·控制用PC（Ubuntu 20.04/22.04）× 1

·USB数据线（用于连接GELLO）

·网络连接（用于下载依赖包）

2.2 软件依赖

·Python 3.8+

·ROS Noetic / ROS2（根据机械臂驱动要求）

·Git

·pip3

3. 环境配置

首先克隆GELLO软件仓库并设置Python虚拟环境：

# 进入项目目录

cd ~/projects/gello_software/

# 激活虚拟环境

source .venv/bin/activate

提示：确保每次操作前都激活虚拟环境，否则会出现依赖缺失错误。

4. 设备连接与识别

连接GELLO后，需要确认系统识别到串口设备：

# 查看串口设备列表

ls /dev/serial/by-id

正常输出示例：

警告：记录完整的设备串口号，后续步骤需要使用。如果没有任何输出，请检查USB连接和驱动。

5. 关节配置说明

不同机械臂的关节信号方向可能不同，需要根据实际机型配置关节符号参数。以下是常见机型的配置参考：

机器人类型	关节信号参考	自由度	备注
UR	1 1 -1 1 1 1	6	通用机器人
Panda	1 -1 1 1 1 -1 1	7	Franka Panda
FR3	1 1 1 1 1 -1 1	7	Franka FR3
xArm7	1 1 1 1 1 1 1	7	UFACTORY xArm7
YAM	1 -1 -1 -1 1 1	6	YAM协作臂

警告：YAM机械臂的关节符号为：1 -1 -1 -1 1 1。符号表示该关节运动方向与控制输入的关系，错误的符号会导致关节反向运动。

6. 偏移量校准

首次使用或更换机械臂后，需要进行偏移量校准。校准步骤如下：

6.1 将机械臂复位到零位

手动或使用程序将所有关节调整到0度位置。

6.2 运行校准脚本

使用以下命令运行校准程序：

python3 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/复制你的设备串口号

参数说明：

·--start-joints：机械臂当前各关节角度（单位：度）

·--joint-signs：关节运动方向符号（根据第5节表格设置）

·--port：串口设备路径（根据第4节获取的实际路径）

提示：校准完成后，系统会输出偏移量参数，请记录下来供后续使用。

python3 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_FTBTMMRU-if00-port0

7. 代码配置修改

根据校准结果修改GELLO代理配置文件。打开以下文件进行编辑：

gello_software/gello/agents/gello_agent.py

需要修改的内容包括：

·关节符号配置（与第5节一致）

·串口设备路径（与第4节一致）

·偏移量参数（来自第6节校准结果）

提示：修改完成后保存文件。建议先备份原始文件以防万一。

例如：

修改代码gello_software/gello/agents/gello_agent.py

注意：夹持器开合定义：默认Open在前，Close在后，官方仿真中实际相反，以自己的版本为准。

The gripper config of GELLO. This is a tuple of (gripper_joint_id, degrees in open_position, degrees in closed_position). Set to None for robots without a gripper.

8. 启动遥操作

完成以上配置后，可以启动遥操作系统。需要同时运行两个终端：

8.1 终端1：启动机器人节点

cd ~/projects/gello_software/

source .venv/bin/activate

python3 experiments/launch_nodes.py --robot sim_yam

可选的--robot参数：

·sim_yam：YAM仿真模式（测试使用）

·yam：连接真实YAM机械臂

·sim_ur：UR仿真模式

·panda：Franka Panda

·其他支持的机械臂类型

8.2 终端2：启动GELLO代理

cd ~/projects/gello_software/

source .venv/bin/activate

python3 experiments/run_env.py --agent=gello

遥操作如图

此时GELLO控制器应与机械臂建立连接，可以通过控制器进行遥操作。

警告：确保两个终端都已激活虚拟环境，否则会出现模块导入错误。

9. 常见问题排查

Q1: 无法识别串口设备

A: 检查USB连接是否牢固，尝试更换USB端口。如仍无法识别，可能需要安装FTDI驱动。

Q2: 关节运动方向相反

A: 检查--joint-signs参数设置是否正确，参考第5节的配置表格。

Q3: 校准后位置偏差大

A: 确认机械臂校准时确实处于零位，重新执行校准流程。

Q4: 启动时报模块缺失错误

A: 确认已激活虚拟环境，并检查requirements.txt中的依赖是否全部安装。

Q5: 遥操作响应延迟

A: 检查USB连接稳定性，关闭不必要的后台程序，确保控制计算机性能足够。

Q6: 机械臂无响应

A: 检查机械臂电源和急停开关状态，确认ROS节点正常运行。

10. 安全注意事项

10.1 操作前检查

·确保机械臂安装稳固，工作范围内无障碍物

·检查急停开关功能正常

·确认所有人员处于安全区域

10.2 操作过程中

·操作人员应始终监控机械臂运动状态

·发现异常立即按下急停

·禁止在机械臂运动时进入工作区域

10.3 维护保养

·定期检查USB线缆和连接器

·保持控制器清洁，避免液体溅入

·长时间不用时断开电源

10.4 故障处理

·遇到无法解决的问题，先断开电源

·记录错误信息，联系技术支持

·不要自行拆卸Gello或机械臂

警告：安全第一！遥控操作时请务必保持警觉，随时准备应对突发情况。

伯克利开源低成本的示教神器GELLO-3.5.遥操珞石AR5机械臂

Wed, 29 Jul 2026 20:00:00 +0800

注意：此遥操版本为定制版本，如果您需要，请联系我们。

1. 系统概述

GELLO 是一个通用、低成本、直观的机器人遥操作框架。本手册专门介绍如何使用 GELLO 设备对ROKAE珞石 AR5 仿真机器人（MuJoCo 物理引擎）进行遥操作。

2. 环境搭建

2.1.下载源码,克隆官方仓库

参考软件安装

2.2.安装 AR5 补丁包

将 AR5 补丁包中的文件复制到对应位置

2.3硬件连接

将 GELLO 设备通过 USB 连接到电脑，确认设备被识别：

ls /dev/serial/by-id

正常应看到类似 usb-FTDI_USB__-__Serial_Converter_FTBHZC6C-if00-port0 的设备名。

3. 左臂（AR5-5-0.8L）遥操作

3.1 校准

cd ~/projects/gello_software/

source .venv/bin/activate

机器人类型	关节信号参考	自由度
AR5	1 1 1 -1 1 1 1	7

注意：此仿真模型里面没有夹爪。

机械臂主臂如图摆放

python scripts/gello_get_offset.py \
    --start-joints 0 0 0 0 0 0 0 \
    --joint-signs 1 1 1 -1 1 1 1 \
    --port /dev/serial/by-id/usb-FTDI_USB__-__Serial_Converter_FTBHZC6C-if00-port0

将GELLO 摆到零位姿态后执行。输出结果填入 ~/projects/gello_software/gello/agents/gello_agent.py代码的 joint_offsets。

2.2 启动仿真服务器（终端 1）

cd ~/projects/gello_software/

source .venv/bin/activate

python experiments/launch_nodes.py --robot sim_ar5

此时应弹出 MuJoCo 窗口，显示 AR5 左臂模型。

2.3 启动遥操作（终端 2）

cd ~/projects/gello_software/

source .venv/bin/activate

python3 experiments/run_env.py --agent=gello

此时操控 GELLO 设备，MuJoCo中的 AR5 应跟随运动。

伯克利开源低成本的示教神器GELLO-3.6.遥操法奥FR5

Wed, 29 Jul 2026 19:30:00 +0800

构型参考UR5e
http://rosrobot.cn/?id=658

关节信号参考值

机器人类型	关节信号参考	自由度
UR5e	1 1 -1 1 1 1	6
FR5	1 1 -1 1 1 1	6
Panda	1 -1 1 1 1 -1 1	7
FR3	1 1 1 1 1 -1 1	7
xArm7	1 1 1 1 1 1 1	7
YAM	1 -1 -1 -1 1 1	6

将机械臂摆出如下造型进行标定：

具体细节参考：http://rosrobot.cn/?id=658

标定：

python3 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_FTBNWWUF-if00-port0

cd ~/projects/gello_software/

source .venv/bin/activate

python3 experiments/launch_nodes.py --robot sim_fr5

ls /dev/serial/by-id

修改参数：

cd ~/projects/gello_software/

source .venv/bin/activate

python3 experiments/run_env.py --agent=gello

伯克利开源低成本的示教神器GELLO-4.真机实操

Wed, 29 Jul 2026 12:00:00 +0800

参考：https://github.com/wuphilipp/gello_software

1.启动机器人节点

格式：

python experiments/launch_nodes.py --robot <ur|panda|xarm>

例如：panda机器人

python experiments/launch_nodes.py --robot panda

2.启动 GELLO 控制器

python3 experiments/run_env.py --agent=gello

伯克利开源低成本的示教神器GELLO-5.数据收集操作说明

Wed, 29 Jul 2026 11:30:00 +0800

本文档详细介绍如何使用 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/