이 문서는 사람뿐 아니라 Claude Code 같은 AI 에이전트가 그대로 따라 실행할 수 있게 스킬 파일 형식으로 작성됐다. 각 단계는 [실행 명령] → [기대 로그] → [실패 시 대응] 순서다. 마지막 검증: 2026-07-24 (pseudocon 데모 전날, RTX A4000 / Isaac Sim 5.1 / IsaacLab).

실물 OMX-L leader arm(USB, Dynamixel)을 움직이면 Isaac Sim 안의 가상 omx_f(5축+그리퍼)가 1:1 절대 매핑으로 따라온다. S 키로 에피소드를 녹화하고, UI에서 리플레이하고, 후처리 스크립트로 LeRobotDataset(GR00T 학습용)으로 변환한다.

OMX-L (실물) --serial--> teleop script --> Isaac Sim (Sim2Real.usd) --> episode --> LeRobotDataset

/dev/ttyACM0이 없으면 → 케이블/포트 확인. 이게 없으면 아래 전부 진행 불가 (단, --no_leader로 씬 점검만은 가능).

git clone git@github.com:Pseudo-Lab/NVIDIA-RFM-Lab.git   # 이미 있으면 git pull
cd NVIDIA-RFM-Lab

export HF_LEROBOT_HOME=~/Downloads/huggingface/lerobot   # 원하는 경로로
mkdir -p $HF_LEROBOT_HOME/calibration/teleoperators/omx_leader
cp Simulation_Team/calibration/omx_leader/*.json \
   $HF_LEROBOT_HOME/calibration/teleoperators/omx_leader/

왜 순서가 중요한가: omx_leader_arm.json(homing/range) 없이 lerobot이 connect하면 factory 캘리브를 새로 만들면서 모터 EEPROM Homing_Offset을 0으로 덮어쓴다. 이러면 팔의 영점이 날아가서 복구 작업이 필요해진다. 반드시 복사가 먼저다.

저장소 루트에서 (매 실행마다 HF_LEROBOT_HOME export 필요):

conda deactivate 2>/dev/null
export HF_LEROBOT_HOME=~/Downloads/huggingface/lerobot
PYTHONPATH=Simulation_Team/sim2real ~/IsaacLab/isaaclab.sh -p \
  Simulation_Team/sim2real/sim_to_real_so101/scripts/omx_teleop_scene_direct.py \
  --port /dev/ttyACM0 --robot_id omx_leader_arm --leader_type omx

콜드 부팅 1~2분. 에이전트가 실행할 때는 background로 돌리고 로그 파일을 grep으로 감시하는 방식을 권장한다 (> /tmp/teleop.log 2>&1 리다이렉트 후 아래 기대 로그 확인).

[SCENE] gripper_joint_2 mimic 해제: RemoveAPI + ... · API 잔존=False
[SCENE] gripper_joint_2 maxJointVelocity -> 275.0 deg/s (j1 과 대칭)
[SCENE] gripper_joint_2 drive 게인 = joint_1 복사 (stiffness 178000.0 / ... / maxForce 10000000.0)
[SCENE] 파지 개선: 고마찰 재질 핑거 2/toy 3 콜라이더 · torsional 0.5cm · toy 60g/iter32
[SCENE] leader 연결 완료: /dev/ttyACM0 (omx_leader_arm)
[SCENE] zero = json 절대 매핑 (켜지는 즉시 leader 실제 자세로 싱크)
[UI] view mode -> 2분할 (V 순환)

각 줄의 의미: mimic 스프링 해제(종동 핑거 드래그 방지) / 핑거 속도 대칭 / 그리퍼 조임력 대칭 (1만 배 비대칭 버그 수정분) / 파지용 물성치(마찰·질량) / 실물 연결 / 절대 매핑 / 듀얼 뷰포트.

• 대시보드 읽는 법: err = target−actual(°). target 은 joint limit 으로 클램프되므로 leader 를 범위 밖으로 접어도(놓아서 팔꿈치가 접히는 경우 등) err 은 0 근처가 정상. read ms = 시리얼 지연, scene fps = 씬 프레임(정상 ~25 이상).
• 리플레이: OMX Recording 패널에서 에피소드 선택 → Play (자동 reset 후 재생).

라이브 teleop이 안 되는 상황을 대비해 검증된 pick&place 에피소드 2개가 Simulation_Team/sample_episodes/ 에 포함돼 있다 (trajectory만, frames 제외 — 리플레이엔 충분). teleop 실행 전에 레코더 폴더로 복사하면 Recording 패널 콤보에 자동으로 뜬다:

mkdir -p ~/sim2real/datasets/omx_scene_direct
cp -r Simulation_Team/sample_episodes/episode_* ~/sim2real/datasets/omx_scene_direct/

leader 없이 리플레이만 시연하려면 --no_leader 를 붙여 실행하고 Play 하면 된다. (episode_0003/0004 = 2026-07-24 신규약 녹화분. 그 이전 구규약 에피소드는 손목이 90° 어긋나므로 쓰지 말 것.)

kill과 launch를 한 셸 명령에 합치지 말 것 (겹치면 새 프로세스가 즉사한다):

pkill -f omx_teleop_scene_direct.py          # 1) 종료 (exit 144는 정상 노이즈)
# 2) GPU에서 kit/python이 사라질 때까지 대기 (nvidia-smi 폴링, 보통 수 초)
# 3) 1-c 명령으로 단독 실행

1. R — sim을 초기 자세로
2. 실물 leader를 화면 속 sim과 똑같은 자세로 잡는다
3. Z — 그 순간이 새 영점으로 json에 저장된다 (다음 실행부터 자동 적용)

PYTHONPATH=Simulation_Team/sim2real python \
  Simulation_Team/sim2real/sim_to_real_so101/scripts/omx_episodes_to_lerobot.py \
  --episodes_root ~/sim2real/datasets/omx_scene_direct \
  --out_root ~/sim2real/datasets/omx_lerobot

• 에피소드 폴더 구조: episode_NNNN/{frames/*.png, trajectory.jsonl, meta.json}
• 주의: episode_0000~0002는 손목 구규약 녹화분 — 재생/변환 시 joint5가 +90° 어긋난다. episode_0004 이후만 사용할 것.

Simulation_Team/
├── README.md                        ← 이 문서
├── Assets/
│   ├── Sim2Real.usd                 ← 통합 씬 (omx_f/omx_l/tray/toys, cm 단위)
│   └── omx_f/configuration/omx_f_physics.usd  ← 물리 정의 (손목 -90° bake 포함 — 코드와 짝)
├── calibration/omx_leader/          ← leader 캘리브 json 2개 (1-b에서 복사)
└── sim2real/sim_to_real_so101/
    ├── scripts/omx_teleop_scene_direct.py     ← 메인 teleop (이것만 실행하면 됨)
    ├── scripts/omx_episodes_to_lerobot.py     ← LeRobotDataset 변환
    └── utils/                                  ← 매핑·UI·레코더·리플레이