콘텐츠로 이동
GitHub

준비

조립을 마친 뒤 처음 한 번, 컴퓨터가 어느 보드가 어느 팔인지, 서보가 어디까지 움직이는지, 카메라 렌즈가 어떻게 휘어 보이는지 알 수 있도록 설정합니다. 팔은 pinkrab 명령으로, Hermit 과 탑 카메라는 pinkrab-umi 명령으로 설정하며, 결과는 모두 ~/pinkrab/ 아래에 저장됩니다.

설정이 어디까지 됐는지는 언제든 확인할 수 있습니다.

터미널 창
pinkrab doctor
실행 결과
Environment
  / python - 3.12.14
  / lerobot - 0.6.1
  ...

Servos
  / left     - 7/7 responded, 30-34C
  / right    - 7/7 responded, 30-33C

Before starting
  Arms
    / arm boards named (which USB board is which arm) - left, right assigned
    / wall mount measured (base spacing, height above the desk) - mount.yaml
    / left arm calibrated (home pose held, every joint swept) - pinkrab_left.json
    / right arm calibrated (home pose held, every joint swept) - pinkrab_right.json
    ...

/ Environment looks good.

pinkrab doctor 는 아무것도 바꾸지 않고 환경, 연결된 보드, description 을 확인한 뒤, 이 페이지의 단계마다 끝났는지와 남은 단계에서 실행할 명령을 보여 줍니다.

서보 보드 지정

섹션 제목: “서보 보드 지정”

두 팔의 서보 보드는 똑같아서, 운영체제가 붙이는 장치 이름만으로는 어느 보드가 어느 팔인지 알 수 없습니다. 꽂는 순서로 한 번 지정해 두면 이후에는 보드를 뽑았다 다시 꽂아도 같은 팔로 인식합니다.

터미널 창
pinkrab ports detect
실행 결과
Port detection
  Plug order is the only thing that tells the identical boards apart.
  You will unplug these boards, then plug them in one at a time:
    left -> right

[1] Unplug the USB cables of the left and right boards (others may stay), then press ENTER...
[2] Plug in the left board, then press ENTER...
[3] Plug in the right board, then press ENTER...

/ Saved to ~/pinkrab/ports.json
    left     tty.usbmodem5B7B0139551
    right    tty.usbmodem5B790834521

안내에 따라 두 보드를 모두 뽑은 뒤 왼팔 보드, 오른팔 보드 순서로 하나씩 꽂습니다. 지정이 끝난 뒤 팔이 서로 바뀐 것을 알게 되면 pinkrab ports swap 으로 맞바꿉니다.

서보 id

섹션 제목: “서보 id”

STS3215 서보는 모두 공장 출고 id 1 로 나오므로, 같은 버스에 이어 쓰려면 서보마다 id 를 써 넣어야 합니다. id 는 베이스부터 바깥쪽으로 1–7 이고, 앞 단계에서 지정한 팔의 보드로 기록합니다.

터미널 창
pinkrab setup-motors left
pinkrab setup-motors right
실행 결과 · pinkrab setup-motors left
Motor numbering - this writes new ids into servo EEPROM.
  Do not run it on servos that already work. It is for a servo that was
  replaced, or an arm whose numbering is wrong or unfinished.
  target: left   tty.usbmodem5B7B0139551
  order:  gripper -> wrist_roll -> wrist_yaw -> wrist_flex -> elbow_flex -> shoulder_lift -> shoulder_pan
  Connect only the servo named on screen, then press ENTER.
  With more than one connected, they all take the id, or the wrong one does.

Proceed? Type 'y' to continue: 
...

화면에 나오는 관절의 서보 하나만 보드에 연결하고 ENTER 를 누르면 그 서보에 id 가 기록됩니다. 서보를 둘 이상 연결한 채로 쓰면 연결된 서보가 모두 같은 id 를 받으므로, 반드시 하나씩 연결합니다. 이미 id 가 있는 서보에는 id 를 다시 부여할 필요가 없고, 다른 id 를 부여하고 싶거나 서보를 교체했을 때만 id 를 다시 입력하면 됩니다. 특정 관절의 id 만 바로 입력하려면 --joints 로 관절을 지정합니다.

터미널 창
pinkrab setup-motors left --joints wrist_roll           # 왼팔 wrist roll 서보 하나만
pinkrab setup-motors right --joints wrist_flex wrist_yaw # 오른팔 두 관절

관절 이름은 shoulder_pan, shoulder_lift, elbow_flex, wrist_flex, wrist_yaw, wrist_roll, gripper 입니다. 관절을 여러 개 지정해도 적은 순서와 상관없이 gripper 쪽부터 베이스 쪽으로 차례로 기록하므로, 위 두 번째 예에서는 wrist yaw 를 먼저, wrist flex 를 나중에 연결합니다.

드래그해서 돌려 보기

서보 응답 확인

섹션 제목: “서보 응답 확인”
터미널 창
pinkrab check
실행 결과
Servo check (read-only)

  left  tty.usbmodem5B7B0139551
    joint          id  ok   position   temp
    shoulder_pan    1  /        2047    31C
    shoulder_lift   2  /        3235    31C
    elbow_flex      3  /         928    30C
    wrist_flex      4  /        2128    30C
    wrist_yaw       5  /        3112    34C
    wrist_roll      6  /        1999    32C
    gripper         7  /        2609    33C

  right  tty.usbmodem5B790834521
    ...

/ All servos responded on 2 arm(s).

각 팔의 서보 7개에 차례로 신호를 보내 응답과 현재 위치, 온도를 보여 줍니다. 서보는 베이스부터 바깥쪽으로 줄줄이 이어져 있어서 중간 연결이 빠지면 그 뒤의 서보가 모두 응답하지 않는데, 이때 check 가 처음으로 응답하지 않은 관절을 알려 주므로 그 관절의 케이블부터 확인하면 됩니다. 여러 서보가 한꺼번에 응답한다고 나오면 id 를 쓰지 않은 서보가 남아 있는 것이니 서보 id 단계로 돌아갑니다.

설치 치수

섹션 제목: “설치 치수”
터미널 창
pinkrab mount
실행 결과
Wall mount
  Two measurements say where the arms are; everything else in mount.yaml
  is derived. Millimetres, Enter keeps the current value.
    1. between the two arm bases, centre to centre
    2. from the desk surface up to the top of a base - the flat face
       its plate, its beam and the cap over the first servo share

  distance between the two arm bases, centre to centre, in mm [480]: 
  height of a base's top face above the desk, in mm [180]: 

/ Written to ~/projects/pinkrab/src/pinkrab_description/config/mount.yaml
    arms      480 mm apart, at y = +240.0 / -240.0 mm
    base top  180 mm above the desk
    The workspace URDF is expanded again by whatever next needs it.

책상 위의 실제 설치 치수 두 가지를 mm 단위로 입력합니다. 기본값은 간격 480 mm, 높이 180 mm 이고, 팔을 다른 간격이나 높이로 달았다면 줄자로 잰 값을 넣습니다. Enter 만 누르면 지금 값을 그대로 둡니다.

  • 두 팔 베이스 중심 사이의 거리. 두 팔의 shoulder_pan 축 사이를 잽니다.
  • 책상 면에서 베이스 윗면까지의 높이. 베이스 판, 빔, 첫 서보의 덮개가 함께 이루는 평평한 윗면까지 잽니다.
정면 — 팔 간격과 높이
옆면 — 높이를 재는 면

값은 src/pinkrab_description/config/mount.yaml 에 저장됩니다.

이 값으로 두 팔이 책상 좌표계의 어디에 있는지가 정해지고, inverse kinematics 와 시뮬레이션이 같은 값을 씁니다.

팔 calibration

섹션 제목: “팔 calibration”

calibration 은 팔마다 따로 하며, 팔을 home 자세로 잡고 시작한 뒤 모든 관절을 끝에서 끝까지 움직여 각 관절이 실제로 움직이는 범위를 서보에 기록합니다. 벽에 단 팔이 움직일 공간을 먼저 비워 둡니다.

터미널 창
pinkrab calibrate left
pinkrab calibrate right
  1. 시작하면 토크가 풀려 팔을 손으로 움직일 수 있습니다.
  2. 팔을 아래 그림의 home 자세로 잡고 gripper 를 닫은 뒤 ENTER 를 누릅니다.
  3. 관절을 하나씩 한쪽 끝에서 반대쪽 끝까지 천천히 움직이고, 모두 마치면 ENTER 를 누릅니다.

드래그해서 돌려 보기

home 자세는 다음과 같습니다.

  • shoulder pan: 어깨가 보드 정면을 향합니다.
  • shoulder lift: 위팔을 뒤로 젖혀 베이스 윗면 바로 위에 눕힙니다.
  • elbow flex: 아래팔을 앞으로 접어 위팔 위에 포갭니다.
  • wrist flex: wrist yaw 브래킷이 어느 쪽으로도 기울지 않게 가운데에 둡니다.
  • wrist yaw: 손목을 브래킷 입구의 벽에 닿을 때까지 돌립니다.
  • wrist roll: 집는 면이 벽과 수직이 되게 하고, claw 를 바깥쪽에 둡니다.

wrist roll 을 포함해 모든 관절을 끝까지 움직여야 합니다. wrist roll 은 claw 와 wrist 에 출력된 걸림턱이 서로 만나는 ±175° 에서 멈추고, calibration 에서 찾은 끝이 그대로 서보의 한계값이 되기 때문입니다. 결과는 ~/pinkrab/calibration/robots/pinkrab_follower/ 에 팔마다 저장됩니다.

손목 카메라

섹션 제목: “손목 카메라”

두 팔의 손목 카메라도 똑같은 모델이라, 안내에 따라 하나씩 꽂아 어느 카메라가 어느 팔인지 지정합니다.

터미널 창
pinkrab cameras
실행 결과
  Naming the follower arm cameras by their USB sockets, one plug at a time.

  UNPLUG both follower arm cameras - then press Enter
  ...

그다음 팔마다 렌즈를 측정합니다. 아래의 ChArUco 보드를 A4 에 실제 크기로 출력해 평평한 판에 붙이고, 카메라 앞에서 보드의 거리와 각도를 바꿔 가며 보여 줍니다. 쓸 만한 장면은 자동으로 저장되고, 충분히 모이면 fit 으로 렌즈 값을 계산합니다.

A4 가로 한 장에 9 × 6 칸의 ChArUco 보드. 흰 칸마다 ArUco 마커가 있고, 보드 아래에 규격이 적혀 있습니다.
A4 가로, 100 % 로 출력합니다. 보드 아래에 적힌 크기(270 × 180 mm)를 자로 재어 확인합니다.lens_charuco_a4.pdf 내려받기
터미널 창
pinkrab lens capture left
pinkrab lens fit left
pinkrab lens capture right
pinkrab lens fit right
실행 결과 · pinkrab lens fit left
  follower_left: rms 0.697 px over 30 views (worst 0.94 px), seen out to 75 deg off axis
    f 538.0 / 539.6 px/rad, centre (947.5, 578.9), k -0.0481, +0.0121, -0.0138, +0.0038
    image circle 1473 px across, centre (928, 592)
    against left: lens axis -13.9, -26.5 px, f -0.8 px/rad (-0.1 %)
  written: ~/pinkrab/lens.yaml

Hermit

섹션 제목: “Hermit”

Hermit 도 팔과 같은 순서로 설정합니다.

터미널 창
pinkrab-umi setup-motor umi_left   # 새 서보에만, 하나씩 연결해서
pinkrab-umi setup-motor umi_right
pinkrab-umi detect                 # 왼손, 오른손 보드 순서로 꽂아 지정
pinkrab-umi check umi_left
pinkrab-umi check umi_right
pinkrab-umi calibrate umi_left
pinkrab-umi calibrate umi_right
pinkrab-umi cameras                # 안내에 따라 하나씩 꽂아 지정
실행 결과 · pinkrab-umi detect
[1] Unplug the USB cables of the umi left and umi right boards (others may stay), then press ENTER...
...

Hermit 의 서보는 jaw 를 움직이지 않고 jaw 가 열린 정도만 읽기 때문에, calibration 에서는 jaw 를 완전히 닫았을 때와 끝까지 열었을 때의 서보 위치만 기록합니다. 렌즈는 손목 카메라와 같은 방법으로 측정합니다.

터미널 창
pinkrab-umi lens capture left
pinkrab-umi lens fit left
pinkrab-umi lens capture right
pinkrab-umi lens fit right
실행 결과 · pinkrab-umi lens fit left
  left: rms 0.560 px over 30 views (worst 0.99 px), seen out to 88 deg off axis
    f 538.8 / 540.4 px/rad, centre (961.4, 605.4), k -0.0418, +0.0004, -0.0040, +0.0007
    image circle 1553 px across, centre (962, 604)
    against follower_left: lens axis +13.9, +26.5 px, f +0.8 px/rad (+0.1 %)
  written: ~/pinkrab/lens.yaml

탑 카메라

섹션 제목: “탑 카메라”

탑 카메라는 그리퍼 카메라와 같은 모듈이라 꽂힌 USB 소켓으로 구분합니다. 안내에 따라 탑 카메라만 뽑았다가 다시 꽂으면 그 소켓이 탑 카메라로 지정되고, 그리퍼 카메라는 꽂혀 있어도 됩니다.

터미널 창
pinkrab-umi cameras --top
실행 결과
  Naming the top camera by its USB socket - the gripper cameras may stay plugged in.

  UNPLUG the top camera - then press Enter
  ...

렌즈도 같은 ChArUco 보드로 측정합니다. 탑 카메라는 렌즈 값을 측정해야 마커 pose 를 계산하므로, 측정하기 전에는 수집 화면이 마커를 풀지 않습니다. 보드를 책상에서 들어 올려 여러 방향으로 30–45° 기울이고, 가까이와 멀리, 화면 구석까지 옮겨 가며 보여 줍니다.

터미널 창
pinkrab-umi lens capture top
pinkrab-umi lens fit top
실행 결과 · pinkrab-umi lens fit top
  top camera: rms 0.465 px over 20 views (worst 0.67 px)
    f 605.2 / 608.2 px (+-0.19%), centre (1045.8, 636.5), k +1.9460, +2.4231, -0.0005, +0.0003, +0.3098, +2.0318, +2.2415, +0.5145
    it started from f 603.7 / 606.7, centre (1045.7, 636.5): f +0.25 %, centre +0.1, -0.0 px
  written: ~/pinkrab/lens.yaml - the live view solves with it from its next start

측정하는 동안에는 탑 카메라를 쓰는 다른 프로그램(pinkrab-umi live, studio 의 수집 화면)을 끕니다. 렌즈를 바꾸면 ~/pinkrab/lens/top 을 비우고 다시 측정합니다.

마지막으로 pinkrab doctor 를 다시 실행해 모든 항목이 끝났는지 확인합니다.