Upload 4 files

1. LeRobot Installation.md

@@ -0,0 +1,82 @@
+# LeRobot Setting Guide
+https://huggingface.co/docs/lerobot/installation \
+https://huggingface.co/docs/lerobot/so101
+
+last updated Dec/26/2025
+
+# 1. LeRobot Installation
+
+## 1-1. Python 가상 환경 생성
+```bash
+# Create python 3.10 conda env
+conda create -n lerobot python=3.10 -y
+
+# Activate env
+conda activate lerobot
+```
+
+---
+
+## 1-2. ffmpeg, Rerun 설치
+- 영상 처리를 위해 `ffmpeg` 필요
+- LeRobot 데이터 visualization을 위해 `Rerun` 필요  
+```bash
+conda install ffmpeg=7.1.1 -c conda-forge
+pip install rerun-sdk
+```
+
+---
+
+## 1-3. LeRobot 소스 코드 다운로드
+```bash
+# LeRobot github repo clone
+git clone https://github.com/huggingface/lerobot.git
+cd lerobot
+```
+
+---
+
+## 1-4. LeRobot 설치
+```bash
+pip install -e .
+```
+
+---
+
+## 1-5. 로봇 하드웨어 드라이버
+사용하는 모터에 맞는 드라이버 설치
+
+```bash
+# Feetech motor (SO-100, SO-101)
+pip install -e ".[feetech]"
+
+# Dynamixel motor (Koch, etc.)
+pip install -e ".[dynamixel]"
+```
+
+---
+
+## 1-6. 설치 확인
+
+```bash
+python -c "import lerobot; print(lerobot.__version__)"
+```
+
+---
+
+## (Optional) 시뮬레이션 환경
+특정 시뮬레이션 환경을 사용하려면 추가 패키지 설치
+
+```bash
+# ALOHA 시뮬레이션 환경
+pip install -e ".[aloha]"
+
+# Push-T 시뮬레이션 환경
+pip install -e ".[pusht]"
+
+# 모든 시뮬레이션 환경
+pip install -e ".[aloha,pusht,xarm]"
+```
+
+---
+

2. LeRobot Setting.md

@@ -0,0 +1,187 @@
+# 2. LeRobot Setting
+last updated Dec/26/2025
+
+## 2-1. USB port 찾기
+
+1) Follower arm 보드와 PC를 USB로 연결  
+2) 아래 명령 실행
+
+```bash
+lerobot-find-port
+```
+
+3) 안내에 따라 **Follower arm 보드에서 USB 케이블을 뽑고 Enter**를 누르면, 아래와 같은 결과가 출력됩니다.
+
+```text
+The port of this MotorsBus is '/dev/ttyACM0'
+Reconnect the USB cable
+```
+
+→ 이 경우에 follower arm 보드의 USB 포트는 **`/dev/ttyACM0`** 입니다.
+
+4) Leader arm 보드도 마찬가지로 USB 포트를 찾아줍니다.
+
+5) 각 포트가 어떤 arm(Follower/Leader)에 해당하는지 **반드시 구분**해 두세요.
+
+6) 연결된 USB 포트에 Read/Write 권한 부여
+```bash
+sudo chmod 666 /dev/ttyACM0
+sudo chmod 666 /dev/ttyACM1
+```
+
+## (Optional) Serial number를 기반으로 USB port 고정하는 법
+
+### 1. ttyACM0 serial 확인
+```bash
+udevadm info -a -n /dev/ttyACM0 | grep '{serial}' -m 1
+```
+
+```bash
+# Example print
+ATTRS{serial}=="5A7A057786"
+```
+
+### 2. ttyACM1 serial 확인
+```bash
+udevadm info -a -n /dev/ttyACM1 | grep '{serial}' -m 1
+```
+
+```bash
+# Example print
+ATTRS{serial}=="5A68011549"
+```
+
+### 3. udev rule 생성
+
+```bash
+# udev rule 생성/편집
+sudo nano /etc/udev/rules.d/99-serial.rules
+```
+
+```bash
+  GNU nano 2.9.3                              /etc/udev/rules.d/99-serial.rules
+
+# 아래의 serial number는 예시입니다. 자신의 환경에서 확인한 값으로 반드시 교체하세요.
+SUBSYSTEM=="tty", ATTRS{serial}=="5A7A057786", SYMLINK+="so101_follower"
+SUBSYSTEM=="tty", ATTRS{serial}=="5A68011549", SYMLINK+="so101_leader"
+```
+
+### 4. rule reload / trigger
+```bash
+sudo udevadm control --reload-rules
+sudo udevadm trigger
+```
+
+### 5. 고정 포트 확인
+```bash
+ls -l /dev/so101_*
+```
+
+```bash
+# Example print
+# USB 포트를 꽂는 순서가 바뀌어도 다음 경로로 항상 동일하게 인식
+lrwxrwxrwx 1 root root 7 11월 24 21:46 /dev/so101_follower -> ttyACM0
+lrwxrwxrwx 1 root root 7 11월 24 21:46 /dev/so101_leader -> ttyACM1
+```
+
+---
+
+## 2-2. 모터 ID 설정
+
+- 각 모터의 **고유 ID** 설정을 위해 아래 명령어 실행 후, 터미널에 표시되는 가이드에 따라 **모터를 순서대로 연결**하며 진행
+- 아래 링크의 영상을 보면서 하는 걸 추천합니다. \
+https://huggingface.co/docs/lerobot/so101#2-set-the-motors-ids-and-baudrates
+
+### Follower
+```bash
+lerobot-setup-motors \
+  --robot.type=so101_follower \
+  --robot.port=/dev/so101_follower  # Follower 보드의 USB port
+```
+
+### Leader
+```bash
+lerobot-setup-motors \
+  --teleop.type=so101_leader \
+  --teleop.port=/dev/so101_leader   # Leader 보드의 USB port
+```
+
+---
+
+## 2-3. Calibration
+
+- Calibration은 로봇 팔의 각 관절(joint)이 정확한 위치를 인식하고 매핑할 수 있도록 하는 중요한 과정입니다.
+- 아래 링크의 영상을 보면서 하는 걸 추천합니다. \
+https://huggingface.co/docs/lerobot/so101#calibrate
+
+### Follower
+```bash
+lerobot-calibrate \
+  --robot.type=so101_follower \
+  --robot.port=/dev/so101_follower \
+  --robot.id=follower
+```
+
+### Leader
+```bash
+lerobot-calibrate \
+  --teleop.type=so101_leader \
+  --teleop.port=/dev/so101_leader \
+  --teleop.id=leader
+```
+
+### Calibration 과정
+Command 실행 후 다음과 같은 메시지가 표시됩니다.
+
+```text
+Move None SO101Leader to the middle of its range of motion and press ENTER....
+Move all joints sequentially through their entire ranges of motion.
+Recording positions. Press ENTER to stop...
+```
+
+위 메시지를 따라 **중간 위치(middle position)** 를 잡아주고 **Enter**를 눌러주세요.
+
+#### Joint 움직임 체크리스트
+- 로봇 팔을 **중간 위치(middle position)** 로 이동
+- 모든 관절(joints)을 **순차적으로** 전체 범위에서 움직여보기
+- **ENTER** 키를 눌러 기록 중지
+
+### Calibration 결과
+Calibration이 완료되면 다음과 같은 관절 위치 정보가 출력됩니다(예시).
+
+```bash
+-------------------------------------------
+-------------------------------------------
+NAME            |    MIN |    POS |    MAX
+shoulder_pan    |   1955 |   2007 |   3132
+shoulder_lift   |    709 |    724 |   2057
+elbow_flex      |   1605 |   3036 |   3110
+wrist_flex      |    808 |   2797 |   2803
+wrist_roll      |   2037 |   2048 |   2055
+gripper         |   2019 |   2046 |   3383
+```
+
+### 파일 저장 확인
+성공적으로 완료되면 다음 메시지가 표시됩니다.
+
+```bash
+Calibration saved to ~/.cache/huggingface/lerobot/calibration/teleoperators/so101_leader/leader.json
+```
+
+### Calibration 파일
+
+Calibration이 완료되면 다음 위치에 파일이 저장됩니다.
+
+- 리더 암:  
+  `~/.cache/huggingface/lerobot/calibration/teleoperators/so101_leader/leader.json`
+- 팔로워 암:  
+  `~/.cache/huggingface/lerobot/calibration/robots/so101_follower/follower.json`
+
+
+각 Calibration 파일에는 다음 정��가 포함됩니다.
+
+- 각 관절의 최소값(MIN)
+- 현재 위치(POS)
+- 최대값(MAX)
+
+---

3. LeRobot Manipulation.md

@@ -0,0 +1,211 @@
+# 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 뷰어 자동 실행  
+- 카메라 영상, 로봇 액션, 상태 정보 확인 가능  
+
+---
+

4. LeRobot VLA.md

@@ -0,0 +1,246 @@
+# 4. LeRobot VLA
+last updated Dec/26/2025
+
+## 4-1. Train a policy
+
+### Example train command (pi0.5)
+
+#### (A) Multi-GPU (Accelerate)
+- 멀티 GPU를 사용할 경우 일반적으로 `CUDA_VISIBLE_DEVICES`에 노출한 **GPU 개수 = `--num_processes`** 로 맞춥니다.
+
+```bash
+# Multi-GPU example (4 GPUs)
+CUDA_VISIBLE_DEVICES=0,1,2,3 \
+accelerate launch --num_processes=4 $(which lerobot-train) \
+  --wandb.enable=true \
+  --wandb.project=lerobot \
+  --dataset.repo_id=${HF_USER}/${TASK_NAME} \
+  --output_dir=${HF_USER}/pi05_pickplace \
+  --policy.type=pi05 \
+  --policy.pretrained_path=lerobot/pi05_base \
+  --policy.dtype=bfloat16 \
+  --policy.device=cuda \
+  --steps=3000 \
+  --batch_size=64 \
+  --log_freq=100 \
+  --save_checkpoint=true \
+  --save_freq=500 \
+  --policy.push_to_hub=true \
+  --policy.repo_id=${HF_USER}/pi05_pickplace
+```
+
+#### (B) Single GPU
+- 싱글 GPU에서는 `accelerate launch ...` 대신 `lerobot-train`을 직접 실행합니다.
+
+```bash
+CUDA_VISIBLE_DEVICES=0 \
+lerobot-train \
+  --wandb.enable=true \
+  --wandb.project=lerobot \
+  --dataset.repo_id=${HF_USER}/${TASK_NAME} \
+  --output_dir=${HF_USER}/pi05_pickplace \
+  --policy.type=pi05 \
+  --policy.pretrained_path=lerobot/pi05_base \
+  --policy.dtype=bfloat16 \
+  --policy.device=cuda \
+  --steps=3000 \
+  --batch_size=64 \
+  --log_freq=100 \
+  --save_checkpoint=true \
+  --save_freq=500 \
+  --policy.push_to_hub=true \
+  --policy.repo_id=${HF_USER}/pi05_pickplace
+```
+
+| 옵션명 | 설명 | 비고 |
+|---|---|---|
+| `--policy.device` | 사용 device | |
+| `--policy.dtype` | 학습 dtype | |
+| `--steps` | 학습 스텝 수 | |
+| `--batch_size` | 프로세스당 배치 사이즈 | |
+| `--optimizer.grad_clip_norm` | gradient clipping max norm | 초반 발산/NaN을 막는 안전장치. 너무 작으면 학습이 답답해질 수 있어 “안정화 → 필요 시 완화” 순서로 조정하는 게 무난함. |
+| `--num_workers` | DataLoader 워커 수 | |
+| `--dataset.streaming` | 스트리밍 데이터셋 모드 | 데이터를 미리 다 caching하지 않고 순차 공급받는 모드. streaming은 셔플/랜덤 접근이 제한되기 쉬워 학습 곡선이 달라질 수 있음. 데이터가 너무 커서 local cache가 부담인 경우 유리. |
+| `--policy.drop_n_last_frames` | 에피소드 마지막 N프레임 제거 | |
+| `--wandb.enable` | W&B 로깅 사용 여부 | |
+| `--wandb.project` | W&B 프로젝트명 | |
+| `--job_name` | 학습 작업 이름 | |
+| `--output_dir` | 결과/체크포인트 출력 경로 | |
+| `--save_checkpoint` | 체크포인트 저장 여부 | |
+| `--save_freq` | 체크포인트 저장 주기(step) | |
+| `--seed` | 랜덤 시드 | |
+| `--resume` | 체크포인트에서 재시작 | |
+| `--checkpoint_path` | 재시작 체크포인트 경로 | |
+| `--rename_map` | observation 키 이름 매핑 | 데이터셋의 카메라 이름과 policy가 기대하는 카메라 이름이 다를 때 사용. |
+| `--eval_freq` | 학습 중 평가 주기(step) | `eval_freq > 0`이어도 env 설정이 함께 있어야 평가 환경이 만들어짐. |
+| `--eval.batch_size` | 평가용 env 개수(n_envs) | |
+| `--eval.use_async_envs` | 비동기 평가 env 사용 | |
+| `--eval.n_episodes` | 평가 에피소드 수 | |
+| `--env.task` | (시뮬) 평가 태스크 | 시뮬레이션 평가에서 어떤 태스크를 돌릴지 지정. |
+| `--env.max_parallel_tasks` | (시뮬) 평가 병렬 제한 | |
+
+
+### 학습 재시작(resume) 예시
+```bash
+lerobot-train \
+ --resume=true \
+ --checkpoint_path="<checkpoint_dir>"   ... (나머지 동일)
+```
+
+### 학습 중 시뮬레이션 평가 켜기
+학습 중 평가를 돌리려면 `--eval_freq`를 양수로 두고, env 설정과 eval 설정을 함께 지정합니다.
+
+```bash
+lerobot-train \
+  --eval_freq=500 \
+  --env.task="<your_env_task>" \
+  --env.max_parallel_tasks=8 \
+  --eval.batch_size=8 \
+  --eval.use_async_envs=true \
+  --eval.n_episodes=50   ... (나머지 동일)
+```
+
+### (Optional) [RA-BC (Reward-Aligned Behavior Cloning)](https://huggingface.co/docs/lerobot/sarm)
+
+RA-BC는 “그냥 시연을 그대로 따라 배우는(BC)” 대신, **진행이 좋아지는(=성공에 가까워지는) 구간을 더 강하게 학습**하도록 샘플별 가중치를 적용하는 방식입니다.  
+LeRobot 학습 코드에서는 RA-BC를 켜면 배치 안에서 샘플마다 weight를 적용해 **가중 평균 loss**로 업데이트하는 흐름을 탑니다.  
+
+| 옵션명 | 설명 | 부가 설명(언제/왜 쓰는지) |
+|---|---|---|
+| `--use_rabc` | RA-BC 사용 여부 | |
+| `--rabc_progress_path` | progress/가중치 파일 경로 | 사전에 계산된 progress/weight 파일 필요. |
+| `--rabc_head_mode` | progress head 선택 | progress 예측의 어떤 head를 사용할지 선택. |
+| `--rabc_kappa` | 가중치 민감도(세기) | 값이 커질수록 특정 구간에 과도하게 집중할 수 있음. |
+| `--rabc_epsilon` | 수치 안정화 상수 | 분모 0 방지 |
+
+---
+
+## 4-2. Run inference
+
+### 방법 1: Inference by `lerobot-record`
+```bash
+CUDA_VISIBLE_DEVICES=1 \
+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}
+  }" \
+  --dataset.repo_id=${HF_USER}/eval_pi05 \  # The name of dataset begins by eval to reflect that you are running inference (e.g. ${HF_USER}/eval_pi05)
+  --dataset.push_to_hub=false \
+  --dataset.single_task="pick a cup and place on the pink circle." \
+  --policy.path=${HF_USER}/pi05_pickplace \
+  --display_data=true
+```
+
+### 주요 옵션 설명
+| 옵션명 | 설명 |
+|---|---|
+| `--robot.type` | follower 로봇 타입 |
+| `--robot.port` | follower USB 포트 |
+| `--robot.id` | follower 로봇 고유 ID (calibration 때 설정한 ID) |
+| `--robot.cameras` | 카메라 정보 |
+| `--dataset.repo_id` | 기록/평가 데이터를 저장할 HF 데이터셋 repo |
+| `--dataset.push_to_hub` | Huggingface 자동 업로드 여부 |
+| `--dataset.single_task` | language instruction |
+| `--policy.path` | 사용할 정책(모델) 경로 |
+| `--display_data` | 화면에 데이터 표시 여부 (Rerun) |
+
+---
+
+### 방법 2: [Asynchronous inference (PolicyServer + RobotClient)](https://huggingface.co/docs/lerobot/async)
+
+비동기(Async) 추론은 **action prediction(서버)** 과 **action execution(로봇)** 을 분리합니다.  
+로봇은 이미 받은 action chunk를 실행하는 동안, 서버는 다음 chunk를 미리 계산해 “멈칫거림(wait-for-inference)”을 줄입니다.
+
+#### 0) 설치
+
+```bash
+pip install -e ".[async]"
+```
+
+---
+
+#### 1) Policy Server 실행 (서버/별도 터미널)
+
+`PolicyServer`는 처음에는 “빈 컨테이너”로 뜨고, **첫 연결(handshake) 때 클라이언트가 어떤 policy를 어떤 device로 돌릴지**를 전달합니다.
+
+```bash
+# 기본 예시 (localhost:8080)
+CUDA_VISIBLE_DEVICES=0,1,2,3 \
+python -m lerobot.async_inference.policy_server \
+  --host=127.0.0.1 \
+  --port=8080
+```
+
+---
+
+| 옵션명 | 설명 | 부가 설명 |
+|---|---|---|
+| `--host` | 서버 바인딩 주소 | 같은 머신이면 `127.0.0.1`/`localhost`. 네트워크로 붙일 거면 `0.0.0.0` 또는 서버 IP를 사용. |
+| `--port` | 서버 포트 | 기본 `8080`. |
+| `--fps` | 서버 기준 FPS | 기본 30. `environment_dt = 1/fps`로 내부 timestep을 계산. |
+| `--inference_latency` | 목표 추론 지연(초) | 기본 `1/fps`. 서버는 action chunk를 만든 뒤, 이 값에 맞춰 pacing(sleep)합니다. |
+| `--obs_queue_timeout` | observation queue timeout(초) | 기본 2초. timeout 내에 obs가 없으면 서버는 빈 응답을 반환. |
+
+> 참고: 서버는 observation queue를 `maxsize=1`로 두고 “가장 최신 obs” 위주로 처리합니다.
+
+---
+
+#### 2) Robot Client 실행 (로봇/별도 터미널)
+
+클라이언트는 로봇에서 observation을 읽어 서버로 보내고, 서버가 만든 action chunk를 받아 **로컬 큐에 쌓아 실행**합니다.
+
+```bash
+python -m lerobot.async_inference.robot_client \
+  --server_address=127.0.0.1:8080 \
+  --robot.type=so101_follower \
+  --robot.port=/dev/so101_follower \
+  --robot.id=follower \
+  --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}
+  }' \
+  --task="pick a cup and place on the pink circle." \
+  --policy_type=pi05 \
+  --pretrained_name_or_path=${HF_USER}/pi05_pickplace \
+  --policy_device=cuda \
+  --actions_per_chunk=50 \
+  --chunk_size_threshold=0.7 \
+  --aggregate_fn_name=weighted_average \
+  --debug_visualize_queue_size=True
+```
+
+| 옵션명 | 설명 | 부가 설명 |
+|---|---|---|
+| `--server_address` | 서버 주소 | `host:port` 형태. |
+| `--robot.type` | 로봇 타입 | |
+| `--robot.port` | 로봇 포트 | |
+| `--robot.id` | 로봇 ID | |
+| `--robot.cameras` | 카메라 설정 | **키 이름이 policy가 기대하는 이미지 키**와 맞아야 함. (키 불일치 시 이미지가 “없는 것처럼” 들어가거나 전처리에서 문제 발생) |
+| `--task` | language instruction | |
+| `--policy_type` | 정책 타입 | |
+| `--pretrained_name_or_path` | 모델 경로 | |
+| `--policy_device` | (서버) 정책 실행 device | 이 값은 “클라이언트 옵션”이지만, 실제로는 **서버 쪽에서** 모델을 올릴 device를 지정함. |
+| `--actions_per_chunk` | 한 번에 받을 action 수 | 권장 범위는 보통 10~50. 값이 크면 끊김이 줄 수 있지만, 더 먼 horizon 예측으로 오차 누적 가능성이 커짐. |
+| `--chunk_size_threshold` | obs 전송 트리거 | 큐가 “얼마나 비었을 때” 새 obs를 보내 다음 chunk를 미리 계산할지 결정. 값이 클수록 적응성↑(더 자주 업데이트) / 서버 부담↑. |
+| `--aggregate_fn_name` | action 겹침 구간 병합 함수 | action chunk가 겹치면 같은 timestep의 action을 섞음. (예: `weighted_average`, `latest_only`, `average`, `conservative`) |
+| `--debug_visualize_queue_size` | queue 크기 시각화 | 종료 시 queue 크기 변화를 plotting |
+| `--fps` | 클라이언트 제어 루프 FPS | 기본 30. `environment_dt=1/fps`로 sleep을 조절. |
+
+---
+
+#### 3) 튜닝 팁 (actions_per_chunk / chunk_size_threshold)
+
+- `actions_per_chunk` ↑: actions 고갈 위험 ↓ → 끊김 ↓ / 하지만 긴 horizon 예측 → 오차 누적 가능성 ↑  
+- `chunk_size_threshold` ↑: 더 자주 새 chunk 요청 → 적응성 ↑ / 하지만 서버 요청량 ↑ → 추론 파이프라인 부담 ↑
+
+---
+
+#### 4) 자주 나는 문제
+- **서버는 뜨는데 로봇이 안 움직임**: `server_address`가 서버의 `host:port`와 일치하는지, 방화벽/포트가 막혀있지 않은지 확인  
+- **카메라 키 매칭 오류**: `--robot.cameras`의 키 이름이 policy가 기대하는 이미지 키와 일치해야 함  
+- **Stop-and-go**: `actions_per_chunk`를 늘리거나 `chunk_size_threshold`를 키우되, 서버 리소스/네트워크 지연을 함께 고려
+