3. LeRobot Manipulation.md

# 3. LeRobot Manipulation
last updated Dec/26/2025

## 3-1. Teleoperation

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

```bash
lerobot-find-cameras
```

```bash
# 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
```bash
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 계정 설정

```bash
# 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 [토큰 설정 페이지](https://huggingface.co/settings/tokens)에서 새 토큰 생성  
- 권한: `Write` 선택 (나중에 pretrained model을 학습시키는 경우 `Read` 권한도 필요하므로 `Fine-grained` 선택 추천)
- 생성된 토큰을 위 명령어의 `YOUR_TOKEN_HERE`에 입력


### Record command
```bash
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에 이어서 수집해야 합니다.

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

**해결 방법:**
```bash
rm -rf ~/.cache/huggingface/lerobot/${HF_USER}/${TASK_NAME}
```

---

## 3-3. Replay

```bash
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](https://huggingface.co/spaces/lerobot/visualize_dataset) 페이지에서 데이터셋 repo를 입력 후 확인

### 방법 2: 로컬 시각화

```bash
lerobot-dataset-viz \
    --repo-id=${HF_USER}/${TASK_NAME} \
    --episode-index=0   # visualize할 에피소드 번호
```
- Rerun 뷰어 자동 실행  
- 카메라 영상, 로봇 액션, 상태 정보 확인 가능  

---