3. LeRobot Manipulation.md

3. LeRobot Manipulation

last updated Dec/26/2025

3-1. Teleoperation

카메라 index, 스펙, fps 확인

2개 이상의 카메라를 연결해 데이터셋 구축/모델 추론에 활용할 수 있습니다.
PC에 연결된 카메라의 index, 해상도, fps 등 정보를 확인하려면 아래 명령어를 실행하세요.

lerobot-find-cameras

# Example print
--- Detected Cameras ---
Camera #0:
  Name: OpenCV Camera @ /dev/video0
  Type: OpenCV
  Id: /dev/video0
  Backend api: V4L2
  Default stream profile:
    Format: 0.0
    Fourcc: YUYV
    Width: 640
    Height: 480
    Fps: 30.0
--------------------
Camera #1:
  Name: OpenCV Camera @ /dev/video2
  Type: OpenCV
  Id: /dev/video2
  Backend api: V4L2
  Default stream profile:
    Format: 0.0
    Fourcc: YUYV
    Width: 640
    Height: 480
    Fps: 30.0
--------------------

Finalizing image saving...
Image capture finished. Images saved to outputs/captured_images

TIP: 카메라 연결 순서에 따라 index가 달라질 수 있으니, 실행 전후로 항상 lerobot-find-cameras 다음에 .../lerobot/outputs/captured_images에서 캡처된 사진을 통해 각 camera의 포트를 확인하세요.

Teleoperation command

lerobot-teleoperate \
  --robot.type=so101_follower \
  --robot.port=/dev/so101_follower \
  --robot.id=follower_new_gripper \
  --robot.cameras="{ 
    top: {type: opencv, index_or_path: "/dev/video0", width: 640, height: 480, fps: 30}, 
    wrist: {type: opencv, index_or_path: "/dev/video2", width: 640, height: 480, fps: 30}
  }" \
  --teleop.type=so101_leader \
  --teleop.port=/dev/so101_leader \
  --teleop.id=leader \
  --display_data=true

옵션 설명

옵션명	설명	예시 값
--robot.type	follower 로봇 타입	so101_follower
--robot.port	follower USB 포트	/dev/so101_follower
--robot.id	follower 로봇 고유 ID (calibration 때 설정한 ID)
--robot.cameras	카메라 정보	lerobot-find-cameras로 확인한 값
--teleop.type	leader 로봇 타입	so101_leader
--teleop.port	leader USB 포트	/dev/so101_leader
--teleop.id	leader 이름	leader

---

3-2. Record

HuggingFace 계정 설정

# HuggingFace CLI 토큰 로그인
hf auth login --token ${YOUR_TOKEN_HERE} --add-to-git-credential

# 로그인 확인
HF_USER=$(hf auth whoami | head -n 1)
export HF_USER=$(python -c "from huggingface_hub import whoami; print(whoami().get(\"name\", \"\"))")

# (Optional) 영구 환경 변수 설정
echo 'export HF_USER=$(python -c "from huggingface_hub import whoami; print(whoami().get(\"name\", \"\"))")' >> ~/.bashrc
source ~/.bashrc
echo ${HF_USER}

# Task Name 환경 변수 설정
echo export ${TASK_NAME}=TASK_NAME >> ~/.bashrc     # Task 바뀔 때마다 새로 설정

#-------------------------------------------------------------------
# Huggingface 로그인 하지 않고 로컬에서 진행하는 경우
echo export ${HF_USER}=YOUR_NAME >> ~/.bashrc
echo export ${TASK_NAME}=TASK_NAME >> ~/.bashrc
source ~/.bashrc
echo ${HF_USER} && echo ${TASK_NAME}

• HuggingFace 토큰 설정 페이지에서 새 토큰 생성
• 권한: Write 선택 (나중에 pretrained model을 학습시키는 경우 Read 권한도 필요하므로 Fine-grained 선택 추천)
• 생성된 토큰을 위 명령어의 YOUR_TOKEN_HERE에 입력

Record command

lerobot-record \
  --robot.type=so101_follower \
  --robot.port=/dev/ttyACM0 \
  --robot.id=follower_new_gripper \
  --robot.cameras="{ 
    top: {type: opencv, index_or_path: "/dev/video0", width: 640, height: 480, fps: 30}, 
    wrist: {type: opencv, index_or_path: "/dev/video2", width: 640, height: 480, fps: 30}
  }" \
  --teleop.type=so101_leader \
  --teleop.port=/dev/ttyACM1 \
  --teleop.id=leader \
  --dataset.single_task="make a cup of coffee." \
  --dataset.repo_id=${HF_USER}/${TASK_NAME} \
  --dataset.num_episodes=10 \
  --dataset.episode_time_s=1200 \
  --dataset.reset_time_s=3 \
  --display_data=true \
  --dataset.push_to_hub=true \
  --resume=true     # 이미 생성된 데이터셋 repo에 추가로 데이터 수집하는 경우

주요 Record 옵션

옵션	설명
--robot.type	follower 로봇 타입
--robot.port	follower USB 포트
--robot.id	follower 로봇 고유 ID (calibration 때 설정한 ID)
--robot.cameras	카메라 정보
--teleop.type	leader 로봇 타입
--robot.port	leader USB 포트
--teleop.id	leader 로봇 고유 ID (calibration 때 설정한 ID)
--dataset.single_task	language instruction
--dataset.repo_id	데이터셋 repo 이름
--dataset.num_episodes	수집할 에피소드 수
--dataset.episode_time_s	각 에피소드 녹화 시간
--dataset.reset_time_s	에피소드 간 리셋 시간
--display_data	실시간 데이터 시각화 여부 (Rerun)
--dataset.push_to_hub	Huggingface 자동 업로드 여부

Record 시 키보드 단축키

키	기능
→	에피소드 조기 종료
←	에피소드 재기록
ESC	Command 종료 및 업로드

FileExistsError

데이터셋 repo가 이미 존재하면 기존 디렉토리를 덮어쓰지 않고 FileExistsError가 발생하므로 기존 repo를 삭제하거나 --resume=true 옵션으로 기존 repo에 이어서 수집해야 합니다.

FileExistsError: [Errno 17] File exists: '/home/.../so101_pickplace'

해결 방법:

rm -rf ~/.cache/huggingface/lerobot/${HF_USER}/${TASK_NAME}

---

3-3. Replay

lerobot-replay \
    --robot.type=so101_follower \
    --robot.port=/dev/so101_follower \
    --robot.id=follower \
    --dataset.repo_id=${HF_USER}/${TASK_NAME} \
    --dataset.episode=0

주요 옵션

옵션	설명
--dataset.repo_id	재생할 데이터셋 repo 이름
--dataset.episode	재생할 에피소드 번호
--dataset.fps	재생 속도

---

3-4. Visualization (데이터셋 확인)

방법 1: HuggingFace 웹에서 확인

LeRobot Dataset Visualizer 페이지에서 데이터셋 repo를 입력 후 확인

방법 2: 로컬 시각화

lerobot-dataset-viz \
    --repo-id=${HF_USER}/${TASK_NAME} \
    --episode-index=0   # visualize할 에피소드 번호

• Rerun 뷰어 자동 실행
• 카메라 영상, 로봇 액션, 상태 정보 확인 가능

---