소프트웨어 설정

르로봇 설치

LeRobot은 SO-101에 필요한 유일한 소프트웨어 패키지입니다. 서보 통신, 교정, Teleop 및 데이터 기록을 처리합니다.

가상 환경 만들기

python -m venv ~/.venvs/so101
source ~/.venvs/so101/bin/activate   # Windows: .venvs\so101\Scripts\activate

르로봇 설치

pip install lerobot

설치 확인

python -c "import lerobot; print(lerobot.__version__)"

소스에서 설치(선택 사항 - 최신 기능용)

git clone https://github.com/huggingface/lerobot.git
cd lerobot
pip install -e ".[so101]"

SO-101 로봇 구성

LeRobot에는 SO-101 로봇 구성이 내장되어 있습니다. 팔로어 암(및 두 팔 텔레옵을 사용하는 경우 리더 암)에 대한 USB 포트를 지정합니다.

USB 포트 찾기

# Linux / macOS
ls /dev/ttyUSB*    # typical: /dev/ttyUSB0, /dev/ttyUSB1
ls /dev/tty.usbserial*   # macOS alternative

# Windows — check Device Manager → Ports → COMx

SO-101 구성 YAML

LeRobot은 명령줄이나 YAML 파일에서 인라인 구성을 사용합니다. 단일 암 설정의 경우:

# ~/.lerobot/robots/so101_follower.yaml
robot_type: so101
port: /dev/ttyUSB0   # update to your port
cameras:
  wrist_cam:
    type: opencv
    index_or_path: 0
    fps: 30
    width: 640
    height: 480

두 팔(리더-팔로어) 구성

# ~/.lerobot/robots/so101_bimanual.yaml
robot_type: so101
port: /dev/ttyUSB1      # follower arm
leader_arms:
  main:
    type: so101
    port: /dev/ttyUSB0   # leader arm
cameras:
  top_cam:
    type: opencv
    index_or_path: 0
    fps: 30
    width: 640
    height: 480

테스트 연결

python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB0 \
  --control.type=none   # just connects and reads state

인쇄된 관절 위치 판독값을 확인해야 합니다. 포트 오류가 발생하는 경우 확인하세요. 문제 해결.

서보 교정

절대 인코더를 사용하는 CAN 버스 암과 달리 Feetech STS3215 서보는 영점 위치를 정의하기 위해 교정이 필요합니다. LeRobot은 이를 자동으로 처리합니다.

교정 실행

python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB0 \
  --control.type=calibrate

스크립트는 팔을 특정 위치(각 관절의 홈, 최소, 최대)로 이동하고 각 위치에서 Enter 키를 누르라는 메시지를 표시합니다. 교정 데이터를 다음에 저장합니다. ~/.cache/huggingface/lerobot/calibration/so101/.

교정 위치

LeRobot은 각 관절을 세 가지 포즈로 배치하도록 요청합니다.

• 홈 위치: 팔은 완전히 뻗어 있고 엔드 이펙터는 앞으로 향하고 있습니다.
• 제로 토크 위치: 중력에 의해 자연스럽게 매달린 팔
• 90도 기준: 각 관절의 중간점

교정 확인

python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB0 \
  --control.type=teleoperate   # move arm by hand to verify joint readout

팔을 수동으로 움직입니다(규정 준수 모드). 관절 위치는 집에서 거의 0에 가까워야 하며 각 관절을 움직일 때 부드럽게 증가/감소해야 합니다.

리더-팔로워 원격조작

SO-101은 리더-팔로워 원격 조작을 위해 설계되었습니다. 한 팔(리더)은 손 움직임을 캡처하고 두 번째 팔(팔로워)은 이를 실시간으로 미러링합니다. 이를 통해 최고 품질의 교육 데모가 생성됩니다.

리더-팔로워 텔레오프 시작

python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB1 \
  --robot.leader_arms.main.type=so101 \
  --robot.leader_arms.main.port=/dev/ttyUSB0 \
  --control.type=teleoperate

단일 암 키보드 텔레업(두 번째 암 없음)

팔이 하나뿐인 경우 키보드 제어 모드를 사용하세요.

python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB0 \
  --control.type=teleoperate \
  --control.teleop_keys=true

컴플라이언스/중력 보상 모드

손으로 자유롭게 움직일 수 있도록 리더 암을 낮은 토크 모드로 전환합니다.

python -c "
from lerobot.common.robot_devices.robots.so101 import SO101Robot
robot = SO101Robot(port='/dev/ttyUSB0')
robot.connect()
robot.set_compliance_mode(True)   # arm moves freely under hand guidance
"

Python API 빠른 시작

CLI 스크립트 없이 르로봇 로봇 API를 통해 직접 SO-101을 제어할 수 있습니다.

기본 관절 제어

from lerobot.common.robot_devices.robots.so101 import SO101Robot
import torch

robot = SO101Robot(port="/dev/ttyUSB0")
robot.connect()

# Read current joint positions (6 DOF)
obs = robot.capture_observation()
print("Joint positions:", obs["observation.state"])

# Send joint position command (in degrees, normalized to [-1, 1] range)
action = torch.zeros(6)   # all joints to zero position
robot.send_action(action)

robot.disconnect()

중력 보상(백드라이브 가능 모드)

from lerobot.common.robot_devices.robots.so101 import SO101Robot

robot = SO101Robot(port="/dev/ttyUSB0")
robot.connect()

# Enable backdrive — arm can be moved freely by hand
robot.set_compliance_mode(True)

import time
for _ in range(100):
    obs = robot.capture_observation()
    print(obs["observation.state"])   # prints live joint positions as you move arm
    time.sleep(0.02)

robot.disconnect()

서보 상태 읽기

from lerobot.common.robot_devices.motors.feetech import FeetechMotorsBus

bus = FeetechMotorsBus(port="/dev/ttyUSB0",
                       motors={"joint1": (1, "sts3215"),
                               "joint2": (2, "sts3215"),
                               "joint3": (3, "sts3215"),
                               "joint4": (4, "sts3215"),
                               "joint5": (5, "sts3215"),
                               "gripper": (6, "sts3215")})
bus.connect()
positions = bus.read("Present_Position", ["joint1", "joint2", "joint3"])
print("Positions:", positions)
bus.disconnect()

상위 3가지 일반적인 문제

# Check if the device is listed
ls /dev/ttyUSB*   # Linux
ls /dev/tty.usbserial*   # macOS

# Linux: add yourself to the dialout group (requires logout)
sudo usermod -aG dialout $USER

# Windows: install CP2102 or CH340 USB driver,
# then check Device Manager for COM port number

# 1. Verify 5V power supply is connected and LED on servo board is on
# 2. Check all servo daisy-chain cables are fully seated
# 3. Try scanning for servos directly:
python -c "
from lerobot.common.robot_devices.motors.feetech import FeetechMotorsBus
bus = FeetechMotorsBus('/dev/ttyUSB0', motors={})
bus.connect()
ids = bus.find_motor_ids()
print('Found motor IDs:', ids)
bus.disconnect()
"

# Check calibration file location
ls ~/.cache/huggingface/lerobot/calibration/so101/

# Re-run calibration if the file is missing
python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB0 \
  --control.type=calibrate

# Pass explicit calibration path if needed
python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB0 \
  --robot.calibration_dir=/path/to/calibration \
  --control.type=teleoperate

아직도 붙어있나요? 에 물어보세요 SO-101 포럼 또는 르로봇 GitHub 문제.