칼리브레이션

로봇 팔을 조작하기 전에 팔마다 한 번 칼리브레이션(보정)을 합니다. 기준이 되는 자세와 관절마다 움직일 수 있는 범위를 재서 보정 파일로 저장하는 일입니다. 이 페이지에서는 Physical Labs 의 칼리브레이션 탭에서 SO-101 의 팔로워와 리더를 차례로 보정하는 방법, 보정 파일이 저장되는 곳, 다시 보정할 때 알아 둘 점을 안내합니다. 터미널 명령은 쓰지 않습니다.

학습 목표

  • 칼리브레이션이 무엇을 재고, 왜 팔로워와 리더를 모두 보정해야 하는지 설명할 수 있다.
  • 기역자 기준 자세를 맞추고 보정 시작 → 측정 시작 → 측정 종료 순서로 보정을 끝낼 수 있다.
  • 보정 파일이 어디에 어떤 이름으로 저장되는지 찾을 수 있다.
  • 다시 보정하면 무엇이 바뀌는지 알고, 필요할 때만 다시 보정할 수 있다.

1. 칼리브레이션이란?

1.1. 무엇을 재나

STS3215 모터는 자기 위치를 0~4095 사이의 숫자로만 알려 줍니다. 같은 숫자라도 모터를 어떤 각도로 조립했느냐에 따라 팔의 자세가 달라서, 숫자만으로는 팔이 지금 어떤 자세인지 알 수 없습니다. 칼리브레이션은 두 가지를 재서 숫자와 자세를 이어 줍니다.

재는 것뜻앱에서 하는 일
기준 자세 (home)관절이 가운데쯤에 오는 자세 — 옆에서 보면 ‘ㄱ’ 자인 기역자 자세보정 시작 을 누른 순간의 자세를 기준으로 기록합니다
가동 범위 (MIN · MAX)관절마다 움직일 수 있는 양쪽 끝측정 시작 과 측정 종료 사이에 각 관절을 끝까지 움직여 기록합니다

손목 회전(wrist_roll)은 계속 돌 수 있는 관절이라 범위를 재지 않고 0~4095 전체를 씁니다.

1.2. 왜 해야 하나

1.3. 준비물

준비물설명
저장된 로봇로봇 설정에서 로봇 저장 까지 마친 로봇 (포트 · robot id · teleop id)
모터 ID 셋업모터마다 ID 를 붙이고 가운데(2048) 정렬을 마친 뒤 조립한 팔 (모터 셋업)
로봇 제어 패키지탭을 처음 열 때 설치 카드가 뜨면 설치하기 로 설치합니다 (기능 패키지 설치)
전원 · USB보정할 팔의 보드에 전원을 넣고 USB 를 PC 에 꽂습니다
빈 자리관절을 끝까지 움직일 수 있게 팔 둘레의 물건을 치웁니다
두 손보정하는 동안 팔의 힘이 빠지므로 손으로 받쳐야 합니다

이 페이지의 예시 이름은 로봇 설정과 같습니다: robot id my_so101, teleop id my_so101_leader.


2. [앱] 칼리브레이션 탭 둘러보기

로봇 창고에서 로봇을 열고 칼리브레이션 탭을 누릅니다. 처음 열 때는 칼리브레이션 준비 중입니다 가 잠깐 뜰 수 있습니다.

칼리브레이션 탭의 연결 설정 칸(포트 · 새로고침 · ID 목록 · 연결 · 빨간 상태 점)과 저장된 캘리브레이션 칸

3D 보기 아래의 연결 설정 칸과 저장된 캘리브레이션 칸. 아직 보정하지 않아 저장된 캘리브레이션 없음 — 캘리브레이션을 먼저 실행하세요. 가 보입니다 (그림의 포트 이름은 촬영한 PC 의 값입니다).

위치이름하는 일
왼쪽로봇 팔 목록 — follower arm · leader arm보정할 팔을 고릅니다
왼쪽 아래보정 시작 (보정 중에는 중단 · 측정 시작, 측정 중에는 빨간 측정 종료)보정을 진행합니다
오른쪽 위3D 보기기준 자세를 보여 주고, 연결하면 실물을 따라 움직입니다. 아래 손잡이를 끌어 높이를 바꿉니다
오른쪽연결 설정 — 포트: · 새로고침 · ID 목록: · 연결 · 상태 점(빨강 → 초록)고른 팔에 연결합니다
연결한 뒤모니터링 및 제어 — 모터마다 모터 ID: n · 슬라이더 · 현재 값:모터 위치를 보여 줍니다
맨 아래저장된 캘리브레이션저장된 보정 값을 보여 줍니다 (5.2절)

포트: 목록에는 로봇 설정에서 고정한 이 로봇의 이름(/dev/my_so101, /dev/my_so101_leader)만 보입니다. 이름 뒤에 (연결 안 됨) 이 붙어 있으면 그 팔의 USB 를 뽑았다가 다시 꽂고 새로고침 을 누릅니다.

모니터링 슬라이더는 실제 모터를 움직입니다

연결한 뒤 보이는 슬라이더를 끌면 그 모터에 힘(토크)이 들어가고 곧바로 그 위치로 움직입니다. 부딪힘을 막아 주는 장치는 없습니다. 보정하는 동안에는 슬라이더를 건드리지 마세요.


3. [앱] 팔로워 보정하기

팔로워와 리더 중 어느 쪽을 먼저 해도 됩니다. 이 페이지에서는 왼쪽 목록 순서대로 팔로워 → 리더로 진행합니다. 보정은 한 번에 한 팔씩 합니다.

3.1. 기역자 자세로 놓고 연결

  1. [앱] 왼쪽 로봇 팔 에서 follower arm 을 누릅니다.
  2. [앱] 포트: 가 팔로워의 고정 이름(/dev/my_so101)인지 확인합니다. ID 목록: 은 1,2,3,4,5,6 그대로 둡니다.
  3. [로봇] 실물 팔을 3D 보기와 같은 기역자 자세로 놓습니다. 옆에서 보면 윗팔은 위로 곧게 서고, 아래팔과 손목은 앞으로 수평하게 뻗은 모양입니다.
  4. [앱] 연결 을 누릅니다. 상태 점이 초록으로 바뀌고 모니터링 및 제어 칸이 나타나며, 3D 보기가 실물을 따라 움직입니다.

SO-101 팔을 손으로 받쳐 기역자 자세로 맞춘 모습 — 윗팔은 세우고 아래팔과 손목은 앞으로 수평하게

기역자 자세의 예 (사진은 SO-101 리더 팔). 팔로워도 같은 자세로 맞춥니다.

포트 목록에 다른 팔의 이름이 골라져 있을 수 있습니다

포트: 목록에는 팔로워와 리더의 고정 이름이 함께 있고, USB 를 꽂는 순서가 바뀌면 다른 팔의 이름이 미리 골라져 있을 수 있습니다. follower arm 에서는 /dev/my_so101, leader arm 에서는 /dev/my_so101_leader 를 골라야 합니다. 잘못 고른 채 보정하면 다른 팔의 값이 이 팔의 보정 파일로 저장됩니다.

손목 카메라를 달았다면

앱 안내대로 손목 회전 모터(SO-101 은 5번, SO-102 는 6번)를 90° 돌린 자세를 기준으로 삼을 수 있습니다. 어느 자세를 쓰든 리더와 팔로워를 같은 자세로 보정하는 것이 중요합니다.

3.2. 보정 시작 — 기준 자세 기록

  1. [로봇] 팔을 기역자 자세로 손으로 받친 채 둡니다.
  2. [앱] 왼쪽 아래 보정 시작 을 누릅니다. 버튼에 마우스를 올리면 포트: /dev/my_so101 | 로봇 ID: my_so101 와 현재 포즈가 home 으로 기록됩니다. 가 보이니, 누르기 전에 한 번 확인하세요.
  3. [앱] 이미 보정 파일이 있으면 재보정 확인 창(이미 'my_so101' 의 보정 파일이 있습니다. … 재보정을 실행하시겠습니까?)이 뜹니다. 새로 보정하려면 Yes 를 누릅니다 (5.3절).
  4. [앱] 안내가 모터 버스에 연결 중입니다. 잠시만 기다려 주세요. → 현재 포즈를 home 으로 기록하고 있습니다. 로 바뀌며, 지금 자세가 기준(home)으로 기록됩니다.
  5. [앱] 왼쪽 아래 버튼이 중단 · 측정 시작 으로 바뀌고, 3D 보기 아래에 보정 표(관절 | MIN | POS | MAX)가 나타납니다. 아직은 POS(지금 위치)만 바뀝니다.

보정 시작 을 누르는 순간 팔의 힘이 빠집니다

모든 모터의 토크가 꺼져, 팔로워는 무게 때문에 아래로 처질 수 있습니다. 처진 자세가 그대로 기준으로 기록되지 않도록, 누르기 전부터 손으로 받쳐 기역자 자세를 유지하세요. 자세가 흐트러졌다면 중단 하고 3.1절부터 다시 합니다.

3.3. 측정 시작 → 관절을 끝까지 → 측정 종료

  1. [앱] 측정 시작 을 누릅니다. 버튼이 빨간 측정 종료 로 바뀌고 각 관절을 양쪽 끝까지 모두 움직였다고 판단되면 [보정 종료] 를 누르세요. wrist_roll 은 lerobot 기본값(0~4095)을 사용하므로 측정 대상이 아닙니다. 가 보입니다.
  2. [로봇] 관절을 하나씩 천천히, 양쪽 끝까지 움직입니다. 그리퍼도 끝까지 열었다 닫습니다. 움직일수록 보정 표의 MIN 은 작아지고 MAX 는 커집니다.
  3. [앱] 모든 관절의 MIN · MAX 가 더 이상 바뀌지 않으면 빨간 측정 종료 를 누릅니다.

안내 문구의 [보정 종료] 는 측정 종료 버튼입니다

안내에는 [보정 종료] 라고 나오지만 화면의 버튼 글자는 측정 종료 입니다. 같은 버튼이니 빨간 측정 종료 를 누르세요.

움직일 관절 (SO-101):

표의 이름모터움직이는 곳측정
shoulder_pan1 · Base (회전)팔 전체를 좌우로 돌립니다양쪽 끝까지
shoulder_lift2 · Shoulder (어깨)윗팔을 앞뒤로 젖힙니다양쪽 끝까지
elbow_flex3 · Elbow (팔꿈치)팔꿈치를 굽혔다 폅니다양쪽 끝까지
wrist_flex4 · Wrist Flex (손목 상하)손목을 위아래로 꺾습니다양쪽 끝까지
wrist_roll (고정)5 · Wrist Roll (손목 회전)손목을 돌립니다재지 않습니다 (0~4095 전체)
gripper6 · Gripper (그리퍼)집게를 여닫습니다끝까지 열고 닫기

끝까지 움직이지 못한 관절이 있으면

그 관절은 좁은 범위로 저장되어, 나중에 팔로워가 그 끝까지 가지 못하거나 리더와 어긋나게 움직일 수 있습니다. 그럴 때는 다시 보정하세요 (5.3절). 측정하는 동안 케이블이 걸리지 않게 천천히 움직입니다.

3.4. 보정 완료

  1. [앱] 안내가 보정 결과를 파일에 저장하고 있습니다. → 보정이 완료되었습니다. 모니터링을 자동으로 다시 시작합니다. 로 바뀝니다.
  2. [앱] 보정 완료 창에 저장한 파일의 경로가 나옵니다 (보정 파일이 저장되었습니다: …/so_follower/my_so101.json). OK 를 누릅니다.
  3. [앱] 잠시 뒤 팔에 다시 연결되고, 맨 아래 저장된 캘리브레이션 칸에 방금 잰 값이 표로 나타납니다. 이제 3D 보기는 보정 값으로 실물의 자세를 그대로 보여 줍니다.
  4. [로봇] 팔을 손으로 받쳐 편한 자세로 내려놓습니다. 보정이 끝난 뒤에도 팔의 힘은 빠져 있습니다.

텔레오퍼레이션 · 데이터 수집 같은 다른 탭은 다음에 연결할 때 새 보정 파일을 읽습니다.

3.5. 중간에 그만두려면


4. [앱] 리더 보정하기

리더도 순서가 같습니다.

  1. [앱] 왼쪽 로봇 팔 에서 leader arm 을 누릅니다. 포트: 가 리더의 고정 이름(/dev/my_so101_leader)인지 확인합니다.
  2. [로봇] 리더를 팔로워를 보정할 때와 같은 기역자 자세로 놓고, [앱] 연결 을 누릅니다.
  3. [로봇] 자세를 손으로 받친 채 [앱] 보정 시작 → 측정 시작 → [로봇] 관절을 하나씩 양쪽 끝까지 (손잡이 쪽 그리퍼 관절도) → [앱] 측정 종료.
  4. [앱] 보정 완료 창에서 경로(…/so_leader/my_so101_leader.json)를 확인합니다.

두 팔의 보정이 모두 끝나면 텔레오퍼레이션에서 리더로 팔로워를 움직여 볼 수 있습니다.


5. 보정 파일

5.1. 저장 위치와 이름

보정 파일은 LeRobot 이 쓰는 폴더에 <이름>.json 으로 저장됩니다. 팔로워는 robot id, 리더는 teleop id 가 파일 이름입니다.

기종 · 팔파일 (Ubuntu)
SO-101 팔로워~/.cache/huggingface/lerobot/calibration/robots/so_follower/<robot id>.json
SO-101 리더~/.cache/huggingface/lerobot/calibration/teleoperators/so_leader/<teleop id>.json
SO-102 팔로워~/.cache/huggingface/lerobot/calibration/robots/so102_follower/<robot id>.json
SO-102 리더~/.cache/huggingface/lerobot/calibration/teleoperators/so102_leader/<teleop id>.json

예를 들어 robot id 가 my_so101 이면 팔로워 파일은 …/robots/so_follower/my_so101.json 입니다. 정확한 경로는 보정 완료 창과 저장된 캘리브레이션 칸 위쪽에 나옵니다. ~/.cache 는 숨김 폴더라 파일 관리자에서 Ctrl+H 를 눌러야 보입니다. 저장된 캘리브레이션 칸의 파일 열기 를 누르면 그 폴더가 바로 열립니다.

5.2. 저장된 캘리브레이션 칸

보정 파일이 있으면 이 칸에 파일 경로와 값의 표가 보입니다.

열뜻
관절 · ID관절 이름과 모터 ID
drive_mode회전 방향입니다. 앱으로 보정하면 늘 0 입니다
homing_offset기준 자세가 가운데 값(약 2047)이 되도록 모터에 기록한 보정 값입니다
range_min · range_max잰 가동 범위입니다. wrist_roll 은 0 · 4095 입니다
버튼하는 일
다시 불러오기파일을 다시 읽어 표를 새로 채웁니다
저장하기표에서 고친 값을 파일에 덮어씁니다 (캘리브레이션 저장 확인 창)
파일 열기보정 파일이 있는 폴더를 파일 관리자로 엽니다

표의 값은 꼭 필요할 때만 고치세요

칸 아래 빨간 안내(주의: 이 값은 캘리브레이션 캐시 JSON 입니다. 모터 EEPROM 과 불일치 시 텔레오퍼레이션이 실패할 수 있으니 신중히 수정하세요.)대로, 잘못 고치면 텔레오퍼레이션이 실패할 수 있습니다. 값이 이상하면 손으로 고치기보다 다시 보정하는 편이 안전합니다. 칸을 고치면 제목이 저장된 캘리브레이션 * 로 바뀌고, 저장하기 를 눌러야 파일에 반영됩니다. 칸에는 정수만 넣을 수 있고, drive_mode 는 0 또는 1 만 됩니다.

5.3. 다시 보정하면

다시 보정하는 것이 좋은 때:

상황까닭
모터를 바꿨거나 팔을 다시 조립했을 때모터가 붙은 각도가 달라졌습니다
텔레오퍼레이션에서 리더와 팔로워의 자세가 눈에 띄게 어긋날 때기준 자세나 범위가 잘못 잡혔을 수 있습니다
측정할 때 어떤 관절을 끝까지 움직이지 못했을 때그 관절의 범위가 좁게 저장됐습니다
robot id · teleop id 를 바꿨을 때파일 이름이 이름을 따라가므로 새 이름의 파일이 없습니다
다른 PC 에서 같은 팔을 쓸 때보정 파일은 PC 에 저장됩니다. 그 PC 에서 다시 보정하거나, 같은 경로 · 같은 이름으로 파일을 복사합니다

로봇을 삭제하면 보정 파일도 지워집니다

로봇 설정의 로봇 삭제 는 그 로봇의 팔로워 · 리더 보정 파일을 함께 지웁니다. 같은 팔을 다시 등록하면 다시 보정해야 합니다.


6. 기종 · 운영체제에 따른 차이

6.1. SO-102 (7축)

다른 점내용
ID 목록:1,2,3,4,5,6,7
보정 표wrist_yaw 행(5번 모터, 손목 좌우)이 더 있고, 이 관절도 양쪽 끝까지 잽니다. wrist_roll (고정) 은 6번, gripper 는 7번입니다
손목 카메라 기준 자세손목 회전은 6번 모터입니다
리더리더도 7축입니다. 같은 순서로 보정합니다
파일 폴더so102_follower · so102_leader — 이름이 같아도 SO-101 보정과 섞이지 않습니다

6.2. LeKiwi (A-Go)

LeKiwi 는 팔로워 팔이 로봇 안의 라즈베리파이에 연결되어 있어서, 왼쪽 목록에 follower arm (lekiwi) 로 보이고 보정도 로봇이 합니다. 앱은 로봇의 게이트웨이(웹 화면 서버)가 하는 보정을 조종하고 진행 상황을 보여 주며, 보정 파일은 로봇 안에 저장됩니다. 화면과 순서가 이 페이지와 조금 다르니 A-Go 캘리브레이션을 따르세요. leader arm 은 노트북에 꽂은 SO-101 리더 팔이라 4절과 똑같이 보정합니다.

6.3. Windows

Windows(최신 0.1.7)에서도 보정 순서는 같습니다

포트가 COM3 처럼 보이고, 보정 파일은 사용자 폴더(%USERPROFILE%) 아래의 같은 모양 경로(.cache\huggingface\lerobot\calibration\…)에 저장됩니다. 시리얼 포트 권한 문제 창은 없습니다. SO-102 와 새 A-Go(ROS 2 LeKiwi)는 Windows 0.1.7 에서 쓸 수 없습니다.


7. 문제 해결

증상확인할 것
탭 자리에 설치 카드가 뜬다 / lerobot 미설치 창칼리브레이션에는 로봇 제어 패키지 가 필요합니다. 설치 카드의 설치하기 로 설치합니다 (기능 패키지 설치)
보정 시작 이 흐려서 눌리지 않는다버튼에 마우스를 올려 이유를 봅니다. 로봇 설정에서 follower 포트를 먼저 저장하세요. · 로봇 설정에서 로봇 ID 를 먼저 저장하세요. 이면 로봇 설정에서 로봇 저장 을 합니다. 먼저 [🔌 연결] 을 눌러 실물과 시뮬을 동기화하고, … 이면 연결 부터 누릅니다
포트: 에 (연결 안 됨) 이 붙어 있다그 팔의 USB · 전원을 확인하고, 케이블을 뽑았다 다시 꽂은 뒤 새로고침 을 누릅니다
연결 을 누르자 시리얼 포트 권한 문제 창이 뜬다Ubuntu 시리얼 권한 문제입니다. 로봇 설정 6절대로 자동 설정 실행 → 다시 연결 시도 를 합니다
연결 오류 — 모터 연결 실패: …포트: 가 그 팔의 이름인지(팔로워 화면에서 리더 이름을 고르지 않았는지), 보드 전원이 켜져 있는지, 다른 탭 · 터미널 프로그램이 같은 포트를 쓰고 있지 않은지 봅니다
N번 모터에서 응답이 없어 통신에 실패했습니다.창의 흔한 원인 (가능성 높은 순): 대로 봅니다 — 같은 ID 모터가 두 대인지, 다른 프로그램이 포트를 쓰는지, 전원 · 배선, 리더 · 팔로워 포트가 바뀌었는지
보정 실패 — 아래 모터의 위치가 보정 가능 범위를 벗어나 홈 위치를 기록할 수 없습니다.창에 나온 모터가 가운데 정렬 없이 조립된 경우입니다. 그 모터를 모터 셋업의 마법사로 다시 셋업(가운데 2048 정렬 포함 — 조립된 팔에서 하는 방법도 그 문서에 있습니다)한 뒤 다시 보정합니다. 창 안의 모드 선택 → 'ID 셋업' 은 예전 메뉴 이름이고, 지금은 사이드바 모터 셋업 또는 로봇 설정 탭의 모터 칸입니다
보정 시작 을 누르자 팔이 툭 떨어졌다토크가 꺼져서입니다. 자세가 흐트러진 채 기록됐을 수 있으니 중단 하고, 팔을 받친 채 3.1절부터 다시 합니다
측정 중 MIN · MAX 가 바뀌지 않는다그 관절이 실제로 움직였는지, 3D 보기가 따라 움직이는지 봅니다. wrist_roll (고정) 은 원래 바뀌지 않습니다
연결했더니 3D 보기가 실물과 다르게 움직인다보정 파일이 없을 때는 연결 하는 순간의 자세를 3D 의 기역자 자세로 삼습니다. 연결 해제 하고, 실물을 3D 와 같은 기역자 자세로 놓은 뒤 다시 연결 합니다
보정했는데 텔레오퍼레이션에서 리더와 팔로워 자세가 어긋난다두 팔을 같은 기역자 자세로 보정했는지, 관절을 끝까지 움직였는지 봅니다. 아니면 5.3절대로 다시 보정합니다
다른 탭에서 팔로워 보정 정보가 없습니다. / 리더 보정 정보가 없습니다.그 팔을 아직 보정하지 않았거나, 보정한 뒤 robot id · teleop id 를 바꾼 경우입니다. 지금 이름으로 다시 보정합니다
보정을 마쳤는데 저장된 캘리브레이션 칸이 계속 저장된 캘리브레이션 없음robot id 가 정확히 follower 이거나 teleop id 가 정확히 leader 이면 이 칸은 파일을 보여 주지 않습니다. 보정 파일은 보정 완료 창에 나온 경로에 저장되어 있고, 다른 탭은 정상으로 씁니다

그 밖의 문제는 문제 해결을 보세요.


8. 정리