2단계: 핸드·양팔 캘리브레이션 (Linux)
본 단계에서는 3개 장치를 캘리브레이션합니다: 리더 암, 팔로워 암, AmazingHand 핸드. 캘리브레이션은 원격 조작 정확성의 전제이며, 본 단계를 완료해야 원격 조작으로 진행할 수 있습니다.
캘리브레이션 순서: 리더 암 → 팔로워 암+핸드 → 핸드 각도. 각 단계마다 터미널 상호작용(물리 조작 + 키 입력)이 필요합니다.
⚠️ 공통 알림: 본 페이지 명령의 시리얼 포트 인자는 예시 자리표시자이며, 반드시 사용자 머신의 실제 시리얼 포트 경로로 교체해야 합니다(단계 1에서 기록한 시리얼 포트 참조).
사전 조건
단계 1: 환경 구축을 완료함
conda 환경
lerobot이 활성화됨시리얼 포트 권한을 설정함(단계 1의 5절)
3개 장치의 시리얼 포트를 기록함
장치에 전원을 공급하고 독립 전원을 사용
단계 1: 리더 암 캘리브레이션
lerobot-calibrate \
--teleop.type=so101_leader --teleop.port=<leader_arm_port> --teleop.id=amazing_hand_leader
<leader_arm_port>를 사용자 머신의 실제 경로로 교체하세요(예시/dev/ttyACM1).
조작 단계：
리더 암의 모든 관절을 중간 위치로 이동하고 Enter를 누름
각 관절을 순서대로 최대/최소 범위까지 밀어 넣고, 완료 후 Enter를 누름
검증: 캘리브레이션 파일이 자동으로 다음에 저장됩니다 ~/.cache/huggingface/lerobot/calibration/teleoperators/so_leader/amazing_hand_leader.json
⚠️ 주의 1(그리퍼 필수)：6번 그리퍼 서보 범위가
gripper.pos(0~100)의 정규화 기준이 됩니다. 그리퍼는 반드시 완전히 열린 상태에서 완전히 닫힌 상태까지 움직여 정확히 캘리브레이션해야 하며, 그렇지 않으면 핸드 개폐 비율이 왜곡됩니다.
⚠️ 주의 2(자유 회전)：캘리브레이션 시 로봇 암이 자유롭게 회전할 수 있어야 하며, 서보가 무부하인지 확인하세요.
⚠️ 주의 3(권한)：시리얼 포트에서
Permission denied가 보고되면 먼저sudo chmod 666 /dev/ttyACM*를 실행하세요(또는 단계 1에서 udev 규칙을 설정했는지 확인).
단계 2: 팔로워 암 캘리브레이션(핸드 동시 연결)
lerobot-calibrate \
--robot.type=so101_amazing_hand --robot.port=<follower_arm_port> --robot.hand_port=<hand_port> --robot.id=amazing_hand_follower
<follower_arm_port>/<hand_port>를 실제 경로로 교체하세요(예시/dev/ttyACM0//dev/ttyACM2).
조작 단계：
팔로워 암의 5개 관절(6번 없음)을 중간 위치로 이동하고 Enter를 누름
각 관절을 전체 범위로 움직이고 Enter를 누름
검증: 캘리브레이션 파일이 다음에 저장됩니다 ~/.cache/huggingface/lerobot/calibration/robots/so101_amazing_hand/amazing_hand_follower.json
⚠️ 주의 1(핸드 토크 자동 활성화)：이 명령은 연결 시 8개 핸드 서보의 토크를 자동으로 활성화합니다(로그에
enabling AmazingHand torque표시). 캘리브레이션 종료 시 핸드가 열리는 것은 정상적인 현상입니다.
⚠️ 주의 2(핸드 GUI가 뜨지 않음)：핸드 각도는 lerobot의
RangeFinderGUI를 사용하지 않으며, 팔로워 암 캘리브레이션이 끝나면 완료됩니다. 핸드 각도는 단계 3의 전용 도구를 사용합니다.
⚠️ 주의 3(시리얼 포트 점유)：이 단계는 핸드 시리얼 포트를 점유합니다. 해당 시리얼 포트를 점유하는 다른 프로세스를 동시에 실행하지 마세요.
단계 3: 핸드 각도 + 그리퍼 방향 캘리브레이션(전용 GUI)
lerobot-calibrate-amazing-hand --hand_port <hand_port> --leader_port <leader_arm_port>
<hand_port>/<leader_arm_port>를 실제 경로로 교체하세요(예시/dev/ttyACM2//dev/ttyACM1).--leader_port는 그리퍼 방향을 동시 캘리브레이션하는 데 사용됩니다(아래 참조).
⚠️ 주의(디스플레이 없는 환경)：GUI는 그래픽 데스크톱이 필요합니다. 디스플레이 없는/SSH 환경에서 실행하면
pygame.error: video system not initialized가 보고됩니다. 해결 방법:
로컬 그래픽 세션에서 실행; 또는
X11 포워딩(
ssh -X)으로 실행.
GUI 조작：
4개 손가락 슬라이더(index/middle/ring/thumb)를 드래그하여 핸드를 완전히 연 상태로 만들고
Save Open클릭슬라이더를 드래그하여 핸드를 완전히 주먹 쥔 상태로 만들고
Save Close클릭리더 암 그리퍼를 열고,
Capture Open클릭(GUI는gripper.pos를 실시간 표시하며, 열었을 때 100에 가까워야 함)리더 암 그리퍼를 집고,
Capture Close클릭(집었을 때 0에 가까워야 함)자동 저장：위 네 값을 모두 설정하면 창 상단에 녹색 배너
AUTO-SAVED to .../hand_angles.json가 나타나고, 터미널에도 경로가 출력됩니다창을 닫음(핸드 토크가 자동 해제됨)
검증: 각도와 그리퍼 매핑이 다음에 저장됩니다 ~/.cache/huggingface/lerobot/calibration/robots/so101_amazing_hand/hand_angles.json
⚠️ 주의 1(반드시 캘리브레이션)：새 PC/새 핸드마다 반드시 본 단계를 실행해야 합니다. config 안의 각도는 AmazingHand 공식 범용 기본값으로, 백업용일 뿐입니다.
hand_angles.json이 존재하면 사용자의 실측값을 우선 로드합니다. 캘리브레이션하지 않으면 개폐 방향/범위가 잘못될 수 있습니다.
⚠️ 주의 2(자동 로드)：로봇은 시작할 때마다
hand_angles.json(gripper_open_pos/gripper_close_pos포함)을 읽어 config 기본값을 덮어씁니다. 코드를 수정할 필요가 없습니다. 그리퍼 방향은 리더 암에 따라 다르므로 한 번만 캘리브레이션하면 됩니다.
⚠️ 주의 3(슬라이더 의미)：슬라이더를
+방향으로 움직이면 해당 손가락의 m1은+angle로, m2는-angle로 이동합니다(미러). 핸드의 실제 자세로 열림/주먹을 판단하고 각도 수치는 신경 쓰지 않아도 됩니다.
⚠️ 주의 4(정밀 캘리브레이션)：캘리브레이션은"완전히 열기"일 때 과도하게 하지 말고(손가락 기울어짐/벌어짐), "완전히 주먹 쥐기"일 때 과도하게 누르지 마세요(서보 지속 가압).
⚠️ 주의 5(Capture 순서)：
Capture Open/Capture Close는 리더 암 그리퍼의 개폐에 대응하며 핸드 손가락이 아닙니다. 핸드의 열림 방향이 반대라면 대부분 여기서 반대로 캘리브레이션했거나 핸드 각도를 반대로 캘리브레이션한 것이므로 다시 캘리브레이션하면 됩니다.
재캘리브레이션
일부만 다시 캘리브레이션하고 싶을 때:
핸드만 재캘리브레이션 → 단계 3만 실행
팔로워 암만 재캘리브레이션 → 단계 2만 실행(핸드 토크도 함께 활성화됨)
전부 재캘리브레이션 → 단계 1 → 2 → 3
⚠️ 주의：단계 2와 단계 3은 동시에 실행할 수 없습니다(둘 다 핸드 시리얼 포트를 점유).
본 단계를 완료한 후 단계 3: 원격 조작으로 진행합니다.
문제 해결
| 현상 | 원인 | 해결 |
|---|---|---|
시리얼 포트 Permission denied | 권한 미설정 | sudo chmod 666 /dev/ttyACM* 또는 udev 설정 |
| 핸드 캘리브레이션 GUI가 열리지 않음 | 그래픽 환경 없음 | 로컬 그래픽 세션에서 실행, 또는 ssh -X 포워딩 |
핸드 드라이버가 Operation timed out 보고 | 시리얼 포트 사용 중/타이밍 | 핸드 시리얼 포트가 점유되지 않았는지 확인 후 재시도 |
| 리더 암 캘리브레이션 시 2307 모델 오류 | 암 버스 오염 | 핸드 시리얼 포트를 동시 연결하지 않았는지 확인; 본 프로젝트의 핸드는 rustypot 경유라 회피됨 |