l2/teleop/ — L2 来源 #3:人类遥操作 (keyboard)

在 pipeline 里的位置

L2 数据生成层最珍贵的一支:人通过键盘实时控制机器人,录下高质量的人类示教轨迹。

数据金字塔角色:量级最小 (10²–10³ 条),但语义最准——VLA 训练通常对 teleop 数据上采样。

当前实现范围

教学最小版,只支持 keyboard:

Se3Keyboard (IsaacLab 自带) 出 7d SE3 delta + gripper;
keyboard_adapter 把 delta 复合到 ee_frame 当前 pose,产出 8d IK-Abs action;
HDF5 schema 与 l2/scripted / l2/rl 严格对齐,L3 convert.py 不需按 source 分支。

不在范围:

SpaceMouse:接口跟 keyboard 一样是 7d SE3 delta,把 Se3Keyboard 替成 Se3SpaceMouse 即可,但需要硬件验证,本仓库教学路径默认不接。
VR / OpenXR / handtracking:需要 CloudXR + 头显,工程复杂度高,留给生产仓库。
Apple Vision Pro / leader-follower:同上。

核心做什么

record.py 是精简版 IsaacLab/scripts/tools/record_demos.py,固化在本任务上的设备配置和 RecorderManager 设定:

[键盘] → Se3Keyboard.advance() → 7d (dx,dy,dz, rx,ry,rz, gripper)
       → keyboard_delta_to_ik_abs(读 ee_frame 当前 pose) → 8d IK-Abs
       → env.step()
       → ActionStateRecorderManagerCfg (与 l2/scripted 同 schema)
       → 连续 N 步 success → 强制 export
       → data/demos/teleop_lift_cube.hdf5

怎么跑

bash

uv run --project l2 python l2/teleop/record.py --num_demos 5

按键 (来自 Se3Keyboard 默认绑定,见 IsaacLab/source/isaaclab/isaaclab/devices/keyboard/se3_keyboard.py:43-50):

操作	按键
平移 ±X	W / S
平移 ±Y	A / D
平移 ±Z	Q / E
转动 roll (绕 X)	Z / X
转动 pitch (绕 Y)	T / G
转动 yaw (绕 Z)	C / V
切换 gripper (开/关)	K
重置当前 episode (丢弃 buffer)	R
暂停录制 (只渲染)	N
恢复录制	M

跑完之后跟 scripted/RL 同样过一遍 schema 检查:

bash

uv run python tools/h5_inspect.py data/demos/teleop_lift_cube.hdf5

关键设计决策

action 空间随设备:keyboard 自然产生 SE3 delta (IK rel),本仓库统一对齐到 8d IK abs。转换由 keyboard_adapter.keyboard_delta_to_ik_abs 完成: abs_pos = ee_pos_curr + dpos、abs_quat = quat_mul(dquat, ee_quat_curr)、 gripper 透传。详见 obs/action 对齐 "三来源转换义务" 表。
几乎一定带 RGB——VLA 训练必需图像,是 teleop 与 scripted/RL 最大的差别。本最小版未加, 按 l2/scripted/env_cfg.py:20-23 的 --with_camera 扩展点同步加即可。
频率 30 Hz(--step_hz 30):贴近 keyboard 体验和人手响应延迟,对应 obs/action 对齐 "频率" 节。
success 走"连续 N 步"+"手动 export":不直接挂 success DoneTerm 触发 auto-reset, 避免 cube 抖动瞬时进圈把 episode 切短。模式来自 IsaacLab 官方 record_demos.py:240-242 / 391-399。
time_out=None:keyboard 操作慢,默认 episode_length_s=5.0 太短,容易在用户还没完成动作时被强制 reset。同 IsaacLab 官方 record_demos.py:257 的做法。
失败轨迹默认丢弃:DatasetExportMode.EXPORT_SUCCEEDED_ONLY (与 scripted/RL 一致)。
不依赖 isaaclab_mimic:IsaacLab 的 record_demos.py 强 import isaaclab_mimic (record_demos.py:123),需要装额外包。本仓库自己写精简版,只依赖 isaaclab.devices。

文件清单

文件	用途
`record.py`	主入口:启动 sim、起 `Se3Keyboard`、跑 30Hz 录制 loop
`env_cfg.py`	基于 `Isaac-Lift-Cube-Franka-IK-Abs-v0`,关 `time_out`、加 success term、挂 `ActionStateRecorderManagerCfg`
`keyboard_adapter.py`	把 `Se3Keyboard.advance()` 的 7d delta 复合到当前 EE pose,产 8d IK-Abs action
`__init__.py`	package 入口(让 `import l2/teleop.*` 工作)

注意事项

Sim 需要 GUI 才能拿键盘焦点,record.py 强制 args.headless = False,即使你传了 --headless 也会被覆盖。
num_envs=1 是硬约束——人一次只能控一台机器人,多 env 也会让 keyboard 的单 7d action broadcast 变得别扭。
灵敏度建议:默认 pos_sensitivity=0.005 m/step、rot_sensitivity=0.02 rad/step。按住 W 不放 ~30Hz × 0.005 ≈ 15 cm/s,够用又不会冲过去。觉得太慢调高 --pos_sensitivity。
上手顺序:scripted → RL → teleop。teleop 实操最容易卡 (键盘节奏感+视角),先把前两个跑通能极大缩短调试时间。

与 IsaacLab 自带 record_demos.py 的差异

不依赖 isaaclab_mimic,精简到 ~150 行。
不支持 XR / IsaacTeleop / SpaceMouse(本最小版)。
直接用 Se3Keyboard,不走 teleop_devices cfg 路径——因为本任务 cfg 没注册 teleop devices,且我们也不要 retargeter 流水线。
把 keyboard 的 IK-rel delta → IK-abs 复合做在脚本侧,不靠 controller 的 rel mode——这样 HDF5 schema 跟 scripted/RL 完全一致。

参考:L2 三种轨迹来源 §3、 obs/action 对齐 "三来源转换义务"、 IsaacLab/scripts/tools/record_demos.py。

l2/teleop/ — L2 来源 #3:人类遥操作 (keyboard) ​

在 pipeline 里的位置 ​

当前实现范围 ​

核心做什么 ​

怎么跑 ​

关键设计决策 ​

文件清单 ​

注意事项 ​

与 IsaacLab 自带 record_demos.py 的差异 ​