LeRobot documentation
LeKiwi
LeKiwi
LeKiwi 모바일 로봇을 조립하는 방법을 아래 단계에서 설명합니다.
부품을 조달합니다
이 README를 따르세요. 부품 목록과 부품 소싱 링크, 그리고 부품을 3D 프린팅하는 방법이 포함되어 있습니다. 3D 프린팅을 처음 하거나 3D 프린터를 소유하지 않은 경우를 위한 조언도 포함되어 있습니다.
유선 버전
wired 버전의 LeKiwi를 사용 중이라면 Raspberry Pi 설치 및 SSH 설정을 건너뛸 수 있습니다. 또한 텔레오퍼레이션을 위한 LeKiwi 스크립트와 리더 암 스크립트 모두를 PC에서 직접 실행할 수 있습니다.
Pi에 소프트웨어 설치
이제 LeKiwi Robot에서 구동될 원격 PC를 설정해야 합니다. 일반적으로 Raspberry Pi를 사용하지만, 5V로 구동되고 카메라 및 모터 제어 보드를 위한 충분한 usb 포트(2개 이상)를 갖춘 어떤 PC도 사용할 수 있습니다.
OS 설치
Raspberry Pi와 SD 카드 설정 방법은 Setup PI를 참고하세요. 여기서는 Raspberry Pi OS 또는 Ubuntu를 설치하기 위해 Imager를 다운로드하는 방법을 설명합니다.
SSH 설정
Pi를 설정한 후에는 Pi에 화면, 키보드, 마우스 없이 노트북에서 로그인할 수 있도록 SSH(Secure Shell Protocol)를 활성화하고 설정해야 합니다. 이를 수행하는 방법에 대한 훌륭한 튜토리얼은 여기에서 찾을 수 있습니다. Pi에 로그인하는 작업은 Command Prompt(cmd)에서 수행할 수 있으며, VSCode를 사용하는 경우 이 확장 기능을 사용할 수 있습니다.
Pi에 LeRobot 설치하기 🤗
Raspberry Pi에 설치 가이드를 사용하여 LeRobot을 설치하세요.
이 지침 외에도 Pi에 Feetech 모터 지원 및 ZeroMQ를 설치해야 합니다:
pip install -e ".[lekiwi]"LeRobot를 로컬에 설치
이미 노트북/PC에 LeRobot을 설치했다면 이 단계를 건너뛰어도 됩니다. 그렇지 않다면, Pi에서 수행했던 동일한 단계를 따라 진행해 주세요.
설치 가이드를 따르세요
이 지침 외에도 노트북/PC에 Feetech 모터 지원 및 ZeroMQ를 설치해야 합니다:
pip install -e ".[lekiwi]"훌륭합니다 🤗! 이제 LeRobot 설치가 완료되었으니 SO100/SO101 암과 모바일 베이스를 조립할 수 있습니다 🤖.
이후 LeRobot을 사용하려면 LeRobot을 설치한 ~/lerobot 폴더로 이동하여 다음 명령어 중 하나를 실행하면 됩니다.
단계별 조립 지침
먼저 SO100/SO101 팔 두 개를 조립합니다. 하나는 모바일 베이스에 부착하고, 다른 하나는 텔레오퍼레이션을 위해 사용합니다. 그런 다음 모바일 베이스를 조립합니다. 조립 방법은 다음 두 페이지에서 확인할 수 있습니다:
모터 보드와 연결된 USB 포트를 찾습니다
각 버스 서보 어댑터의 포트를 찾으려면 다음 스크립트를 실행하세요:
lerobot-find-port
예시 출력:
Finding all available ports for the MotorBus.
['/dev/tty.usbmodem575E0032081']
Remove the USB cable from your MotorsBus and press Enter when done.
[...Disconnect corresponding leader or follower arm and press Enter...]
The port of this MotorsBus is /dev/tty.usbmodem575E0032081
Reconnect the USB cable.발견된 포트는 보드에 해당하는 /dev/tty.usbmodem575E0032081입니다.
Linux에서는 다음을 실행하여 USB 포트에 대한 액세스 권한을 부여해야 할 수 있습니다:
sudo chmod 666 /dev/ttyACM0
sudo chmod 666 /dev/ttyACM1예시 출력:
Finding all available ports for the MotorBus.
['/dev/ttyACM0']
Remove the usb cable from your MotorsBus and press Enter when done.
[...Disconnect corresponding leader or follower arm and press Enter...]
The port of this MotorsBus is /dev/ttyACM0
Reconnect the USB cable.발견된 포트는 보드에 해당하는 /dev/ttyACM0입니다.
모터 구성
모터 설정에 대한 지침은 SO101 문서에서 확인할 수 있습니다. 팔 모터의 id 외에도 모바일 베이스의 모터 id도 설정해야 합니다. 이는 작동하려면 특정 순서로 설정되어야 합니다. 아래는 모바일 베이스의 모터 id와 모터 장착 위치를 보여주는 이미지입니다. LeKiwi에서는 Motor Control 보드를 하나만 사용한다는 점에 유의하세요. 이는 바퀴의 모터 id가 7, 8, 9임을 의미합니다.
LeKiwi의 모터를 설정하려면 이 명령을 실행할 수 있습니다. 먼저 팔의 모터(id 6..1)를 설정한 다음, 바퀴의 모터(9,8,7)를 설정합니다.
lerobot-setup-motors \
--robot.type=lekiwi \
--robot.port=/dev/tty.usbmodem58760431551 # <- paste here the port found at previous step
통신 문제 해결
LeKiwi에 연결하는 데 문제가 발생하면 다음 단계를 따라 문제를 진단하고 해결하세요.
1. IP 주소 구성 확인
명령어나 코드에서 Pi의 올바른 IP가 사용되었는지 확인하세요. Raspberry Pi의 IP 주소를 확인하려면 (Pi 명령줄에서) 다음을 실행하세요:
hostname -I
2. 노트북/PC에서 Pi에 접근할 수 있는지 확인
노트북에서 Raspberry Pi를 ping으로 확인해 보세요:
ping <your_pi_ip_address>
ping이 실패하면:
- Pi가 전원이 켜져 있고 동일한 네트워크에 연결되어 있는지 확인하세요.
- Pi에서 SSH가 활성화되어 있는지 확인합니다.
3. SSH 연결 시도
Pi에 SSH로 연결할 수 없다면 올바르게 연결되어 있지 않을 수 있습니다. 다음을 사용하세요:
ssh <your_pi_user_name>@<your_pi_ip_address>
연결 오류가 발생하면:
- Pi에서 SSH가 활성화되어 있는지 확인하려면 다음을 실행하세요: 그런 다음 다음으로 이동하세요: Interfacing Options -> SSH 그리고 활성화하세요.
sudo raspi-config
교정
이제 리더 암과 팔로워 암을 보정해야 합니다. 휠 모터는 보정이 필요하지 않습니다. 보정 과정은 매우 중요합니다. 한 로봇에서 학습된 신경망이 다른 로봇에서도 작동할 수 있도록 하기 때문입니다.
팔로워 암 보정(모바일 베이스)
팔이 Raspberry Pi에 연결되어 있는지 확인한 후, 이 스크립트 또는 API 예제를 실행하여 팔로어 팔의 보정을 시작합니다 (Raspberry Pi에서 SSH를 통해).
lerobot-calibrate \
--robot.type=lekiwi \
--robot.id=my_awesome_kiwi # <- Give the robot a unique name대부분의 로봇에 대해 보정 방법을 통일했으므로, LeKiwi 암의 보정 단계는 Koch 및 SO101의 단계와 동일합니다. 먼저, 각 관절이 그 범위의 중간에 위치하도록 로봇을 이동한 다음 Enter를 누릅니다. 다음으로, 모든 관절을 전체 운동 범위를 따라 이동합니다. 참고용으로 SO101에 대한 동일한 과정의 영상은 여기에서 확인할 수 있습니다.
유선 버전
wired 버전의 LeKiwi를 사용 중이라면, 모든 명령을 노트북에서 실행하세요.
리더 암 보정
그 다음, 리더 암(노트북/PC에 연결된 부분)을 보정합니다. 노트북에서 다음 API 예제 명령을 실행하세요:
# Use the port of your leader arm, and give the arm a unique name with --teleop.id
lerobot-calibrate \
--teleop.type=so100_leader \
--teleop.port=/dev/tty.usbmodem58760431551 \
--teleop.id=my_awesome_leader_armfrom lerobot.teleoperators.so_leader import SO100LeaderConfig, SO100Leader
config = SO100LeaderConfig(
port="/dev/tty.usbmodem58760431551",
id="my_awesome_leader_arm",
)
leader = SO100Leader(config)
leader.connect(calibrate=False)
leader.calibrate()
leader.disconnect()LeKiwi 원격 조작
Mac을 사용 중이라면, 텔레오퍼레이션(원격 조작)을 위해 터미널에 키보드 접근 권한을 부여해야 할 수 있습니다. 시스템 설정 > 보안 및 개인정보 보호 > 입력 모니터링으로 이동하여 터미널의 확인란을 선택하세요.
원격 조종을 하려면 Raspberry Pi에 SSH로 접속한 후 conda activate lerobot와 다음 명령을 실행하세요:
python -m lerobot.robots.lekiwi.lekiwi_host --robot.id=my_awesome_kiwi
호스트는 --host.connection_time_s 초(기본값 30초) 후 중단됩니다. 데이터셋 녹음과 같은 긴 세션의 경우, 예를 들어 --host.connection_time_s=600로 값을 늘려야 합니다.
그런 다음 노트북에서도 conda activate lerobot을 실행하고 API 예제를 실행하세요. examples/lekiwi/teleoperate.py에서 올바른 remote_ip와 port를 설정했는지 확인하세요.
python examples/lekiwi/teleoperate.py
이제 리더 암을 이동시키고 키보드(w,a,s,d)를 사용하여 전진, 좌측, 후진, 우측으로 주행할 수 있습니다. (z,x)를 사용하여 좌회전 또는 우회전을 수행합니다. (r,f)를 사용하여 모바일 로봇의 속도를 증가 또는 감소시킬 수 있습니다. 세 가지 속도 모드가 있으며, 아래 표를 참조하세요:
| 속도 모드 | 선형 속도 (m/s) | 회전 속도 (deg/s) |
|---|---|---|
| 빠름 | 0.3 | 90 |
| 중간 | 0.2 | 60 |
| 느림 | 0.1 | 30 |
| 키 | 액션 |
|---|---|
| W | 진행하기 |
| A | 왼쪽으로 이동 |
| S | 뒤로 이동 |
| D | 오른쪽으로 이동 |
| Z | 좌회전 |
| X | 오른쪽으로 회전 |
| R | 속도 향상 |
| F | 속도 감소 |
다른 키보드를 사용하는 경우,
LeKiwiClientConfig에서 각 명령에 할당된 키를 변경할 수 있습니다.
유선 버전
wired 버전의 LeKiwi를 사용 중이라면, 모든 명령을 노트북에서 실행하세요.
데이터셋 기록
teleoperation에 익숙해지면 첫 번째 데이터셋을 기록할 수 있습니다.
데이터셋 업로드를 위해 Hugging Face hub 기능을 사용합니다. 이전에 Hub를 사용하지 않았다면, 쓰기 권한이 있는 토큰을 사용하여 cli로 로그인할 수 있는지 확인하세요. 이 토큰은 Hugging Face 설정에서 생성할 수 있습니다.
이 명령을 실행하여 CLI에 토큰을 추가하세요:
hf auth login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential그런 다음 Hugging Face 저장소 이름을 변수에 저장합니다:
HF_USER=$(hf auth whoami --quiet)
echo $HF_USER이제 데이터셋을 기록할 수 있습니다. 에피소드를 기록하고 데이터셋을 허브에 업로드하려면, LeKiwi에 맞게 조정된 이 API 예제를 실행하세요. 먼저 스크립트에서 remote_ip, HF_REPO_ID, 리더 암 port 및 TASK_DESCRIPTION을 상황에 맞게 수정해야 합니다. 더 많거나 긴 에피소드를 기록하려면 NUM_EPISODES, EPISODE_TIME_SEC, RESET_TIME_SEC을 변경하고, 전체 세션을 커버하는 --host.connection_time_s 값으로 호스트를 시작하세요.
python examples/lekiwi/record.py
Dataset 업로드
로컬에서는 데이터셋이 ~/.cache/huggingface/lerobot/{repo-id} 폴더에 저장됩니다. 데이터 기록이 끝나면 스크립트에서 설정한 HF_REPO_ID 아래에 Hugging Face 페이지로 데이터셋이 업로드됩니다(예: https://huggingface.co/datasets/${HF_USER}/lekiwi_test). 다음을 실행하여 확인할 수 있습니다:
echo https://huggingface.co/datasets/${HF_USER}/lekiwi_test데이터세트에는 커뮤니티가 쉽게 찾을 수 있도록 LeRobot 태그가 자동으로 지정되며, 필요에 따라 사용자 정의 태그(예: tutorial)도 추가할 수 있습니다.
LeRobot 태그로 검색하여 허브에서 다른 LeRobot 데이터셋을 찾을 수 있습니다.
데이터 수집 팁
데이터 기록에 익숙해지면 학습을 위한 더 큰 데이터셋을 만들 수 있습니다. 좋은 시작 과제는 물체를 서로 다른 위치에서 집어 바구니에 넣는 것입니다. 최소 50개의 에피소드를 기록하고, 위치당 10개씩 기록하는 것을 권장합니다. 카메라는 고정된 상태로 유지하고, 기록 전반에 걸쳐 일관된 그랩핑 동작을 유지하세요. 또한 조작하는 물체가 카메라에 잘 보이도록 하세요. 좋은 기준은 카메라 이미지만 보고도 본인이 해당 작업을 수행할 수 있을 정도여야 한다는 것입니다.
다음 섹션에서는 신경망을 학습합니다. 안정적인 그립 성능을 달성한 후에는 데이터 수집 단계에서 추가적인 그립 위치, 다양한 그립 기법, 카메라 위치 변경과 같은 더 많은 변형을 도입할 수 있습니다.
결과에 방해가 될 수 있으므로, 변형을 너무 빠르게 많이 추가하지 마세요.
이 중요한 주제를 더 깊이 파고들고 싶으시다면, 좋은 데이터셋의 조건에 대해 작성한 블로그 글을 확인해 보실 수 있습니다.
문제 해결:
- Linux에서 녹화 제어 플로우 키(화살표 키, Escape)는 인터랙티브 터미널에서 녹화를 실행하고 터미널에 포커스가 유지되는 한 X11, Wayland, headless/SSH 세션 모두에서 작동하며
$DISPLAY설정이 필요하지 않습니다. 문자 대안 키n/r/q도 작동합니다. 참고로 LeKiwi 베이스의 키보드 텔레오퍼레이션은 다릅니다. 이는 글로벌 키 백엔드에 의존하므로 X11 세션, Windows 데스크톱, 또는 Accessibility/Input Monitoring 권한이 부여된 macOS에서만 작동하며 Wayland나 headless 머신에서는 작동하지 않습니다. pynput 제한 사항을 참조하세요.
에피소드 재생
에피소드를 재생하려면 아래 API 예제를 실행하고 remote_ip, port, LeRobotDatasetId 및 에피소드 인덱스를 변경해야 합니다.
python examples/lekiwi/replay.py
축하합니다 🎉. 이제 로봇이 스스로 작업을 학습할 준비가 완료되었습니다. 이 튜토리얼의 학습 부분을 통해 학습을 시작하세요: 실제 로봇으로 시작하기
정책 평가
정책을 평가하려면 evaluate.py API 예제를 실행하고, remote_ip, port, 모델 등을 반드시 변경하세요.
python examples/lekiwi/evaluate.py
Update on GitHub질문이 있거나 도움이 필요하시면 Discord로 문의해 주세요.