엔드이펙터로 팔 직접 움직이기
엔드이펙터 탭은 리더 팔 없이 화면에서 팔로워 팔을 직접 움직이는 곳입니다. 관절 각도를 하나씩 바꾸거나, 그리퍼 끝이 갈 좌표(X · Y · Z)를 적거나, 팔을 손으로 잡고 자세를 가르칠 수 있습니다. 처음에는 3D 화면 속 팔만 움직이고, 실물은 🔌 연결 과 Sync 확인 을 마친 뒤 이름에 Real 이 붙은 탭에서만 움직입니다. 움직인 동작은 모션으로 녹화해 두었다가 다시 재생할 수 있습니다.
이 문서는 Ubuntu 판 0.2.0 기준입니다
엔드이펙터는 SO-101(A-Ba)과 새 A-Go(LeKiwi, ROS 2 로봇 — 0.2.0 재배포부터)에서 씁니다. SO-102 는 탭이 잠겨 있습니다 (1.4절). Windows 판(0.1.7)에서 다른 점은 1.6절 끝에 있습니다.
학습 목표
- Joint Control · XYZ Control · Teaching Control 이 각각 무엇을 하는지 설명할 수 있다.
- Sim 과 Real 의 차이를 알고, 🔌 연결 → Sync 확인 순서로 실물을 움직일 수 있다.
- 키보드 · 슬라이더로 관절을 움직이고 속도/힘 을 조절할 수 있다.
- 초기 포즈를 등록하고 모션을 녹화 · 재생할 수 있다.
- 보정 파일 이름 문제처럼 연결이 안 되는 경우에 대처할 수 있다.
1. 엔드이펙터 탭 알아보기
1.1. 엔드이펙터란?
엔드이펙터(end effector)는 로봇 팔 맨 끝에서 실제로 일을 하는 부분입니다. SO-101 에서는 그리퍼(집게)가 엔드이펙터입니다. 이 탭은 그리퍼 끝이 어디에 있는지 좌표로 보여 주고, 관절 각도나 좌표로 팔을 움직입니다.
텔레오퍼레이션이 리더 팔을 손으로 움직여 팔로워를 조종한다면, 엔드이펙터 탭은 화면의 숫자와 키보드로 팔로워를 조종합니다. 팔이 정해 둔 자세로 가는지 확인하거나, 같은 동작을 여러 번 되풀이할 때 쓸모가 있습니다.
1.2. 세 가지 조작 방식
탭 위쪽에 하위 탭 세 개가 있습니다.
| 하위 탭 | 하는 일 | 실물이 움직이는 곳 |
|---|---|---|
| Joint Control | 관절 6개의 각도를 슬라이더 · 키보드 · 숫자로 바꿉니다 | Real Control · Real Motion Record |
| XYZ Control | 그리퍼 끝이 갈 좌표(m)를 적으면 앱이 관절 각도를 계산(역기구학, IK)해 반투명한 팔로 미리 보여 주고, Run 으로 그 자세까지 옮깁니다 | Real Control · Real Motion Record |
| Teaching Control | 모터 힘을 풀고 팔을 손으로 잡아 자세를 만든 뒤, 그 자세들을 저장해 차례로 실행합니다 | 처음부터 실물 전용 |
각 하위 탭은 왼쪽에 3D 보기, 오른쪽에 Control · Motion Record · Motion Replay 탭이 있습니다. Control 에서 움직이고, Motion Record 에서 녹화하고, Motion Replay 에서 다시 재생합니다.
1.3. Sim 과 Real
| 어디서 | 무엇이 움직이나 | 필요한 것 |
|---|---|---|
| Sim Control · Sim Motion Record | 3D 보기 속 팔만 | 없음 — 실물 없이 연습할 수 있습니다 |
| Real Control · Real Motion Record | 3D 와 실물이 함께 | 🔌 연결 + Sync 확인 |
| Motion Replay 에서 Real 체크 | 재생하는 모션을 실물로도 보냅니다 | 🔌 연결 + Sync 확인 |
| Teaching Control | 실물 | 🔌 연결 + Sync 확인 |
Real 에서는 확인 창 없이 실물이 바로 움직입니다
슬라이더를 끌거나 키를 누르는 즉시 팔이 움직입니다. 앱이 막아 주는 것은 관절이 움직일 수 있는 범위(보정할 때 잰 범위)를 넘는 값과, XYZ Control 에서 팔 밑동보다 낮은 자세 정도입니다. 팔이 책상 · 물건 · 사람 · 자기 몸에 부딪히는지는 검사하지 않습니다. 팔 주변을 비우고, 처음에는 속도 를 낮춰서 움직이세요.
1.4. 쓸 수 있는 로봇
| 기종 | 엔드이펙터 탭 |
|---|---|
| SO-101 (A-Ba) | 모든 기능을 씁니다 |
| SO-102 | 탭이 회색으로 잠겨 있습니다. 마우스를 올리면 SO-102 기종은 이 기능이 아직 준비 중입니다. 가 보입니다 |
| Lekiwi (새 A-Go, ROS 2 로봇) | 0.2.0(2026-11-01 재배포)부터 씁니다. 🔌 연결 을 누르면 로봇 팔 연결 확인 창이 뜹니다. SO-101 과 다른 점: 힘 슬라이더는 흉내입니다 (목표가 실제 위치보다 앞설 수 있는 폭을 줄여 미는 힘 · 쥐는 힘을 약하게 합니다). Teaching Control 의 자유 이동은 로봇이 명령 세션을 닫을 때까지 2초쯤 뒤에 힘이 빠지고, 끝낼 때는 로봇이 토크를 켠 것을 확인한 뒤 토크 활성화 가 뜹니다. 웹 화면에서 조작 중이면 로봇이 명령을 거절합니다 |
A-Go(LeKiwi)로 데이터를 모으고 학습 · 추론하는 흐름은 데이터 · 학습 · 추론에 있습니다.
1.5. 시작 전에 준비할 것
| 준비물 | 설명 |
|---|---|
| 저장한 로봇 | 로봇 설정 에서 robot id 와 팔로워 포트를 정하고 로봇 저장 까지 마친 SO-101 → 로봇 설정 |
| 팔로워 보정 | 칼리브레이션 탭에서 follower arm 보정을 마쳐야 연결됩니다 → 칼리브레이션. Sim 으로 연습만 할 때는 없어도 됩니다 |
| 로봇 제어 패키지 | 탭을 처음 열 때 설치 카드가 뜨면 설치하기 를 누릅니다 → 기능 패키지 설치 |
| 팔로워 팔 | USB 케이블을 PC 에 꽂고 모터 전원을 켭니다. 리더 팔은 필요 없습니다 |
| 빈 작업 공간 | 팔이 닿는 범위에 사람 · 물건이 없게 합니다 |
1.6. [앱] 보정 파일 이름 맞추기
로봇 설정의 follower arm 이름 칸은 비워 두세요
지금 Ubuntu 판의 엔드이펙터는 팔로워 보정 파일을 연결하는 포트의 이름으로 찾습니다. 이 이름이 robot id 와 다르면 보정을 마쳤는데도 연결되지 않습니다.
칼리브레이션 탭은 팔로워 보정 파일을 robot id 이름으로 저장합니다. 한편 엔드이펙터 탭은 /dev/<이름> 으로 고정된 포트의 <이름> 으로 보정 파일을 찾습니다. 두 이름이 같아야 연결됩니다.
로봇 설정의 follower arm: 오른쪽 이름 칸을 비워 두면 앱이 robot id 를 그대로 이름으로 씁니다. 그러면 팔로워 포트가 /dev/<robot id> 로 고정되어 두 이름이 저절로 같아집니다.
| robot id | follower arm 이름 칸 | 고정된 팔로워 포트 | 엔드이펙터 연결 |
|---|---|---|---|
my_so101 | (비움) | /dev/my_so101 | 됩니다 |
my_so101 | my_so101 | /dev/my_so101 | 됩니다 |
my_so101 | arm1 | /dev/arm1 | 팔로워 보정 정보가 없습니다. '칼리브레이션' 탭에서 먼저 보정을 진행해 주세요. |
이미 다른 이름을 적어 저장했다면 아래처럼 고칩니다. 보정을 다시 할 필요는 없습니다.
- [앱] 로봇 설정 탭에서 🔓 포트 편집 을 누릅니다.
- [앱]
follower arm:이름 칸을 지웁니다 (robot id 와 똑같이 적어도 됩니다). - [로봇] 팔로워 USB 가 PC 에 꽂혀 있는지 확인합니다. 저장할 때 USB 장치의 시리얼 번호를 읽기 때문입니다. [앱]
follower arm:포트 목록에 팔로워 팔의 포트가 골라져 있는지도 봅니다. 헷갈리면 로봇 설정 3.2절 팁처럼 리더 USB 를 잠깐 뽑아 보며 고릅니다. - [앱] 로봇 저장 을 누르고, 미리보기 창에서 적용 → 관리자 비밀번호를 넣습니다.
- [로봇] 팔로워 USB 케이블을 한 번 뽑았다 다시 꽂습니다.
- [앱] 사이드바 로봇 창고 에서 로봇을 다시 열고 엔드이펙터 탭으로 갑니다. 그래야 엔드이펙터 탭이 새 포트 이름을 읽습니다.
도구 메뉴의 End Effector Control 창보다 엔드이펙터 탭을 쓰세요
위쪽 막대의 도구 메뉴(☰) › End Effector Control 도 같은 조작 화면입니다. 하지만 이 창의 포트 목록에는 로봇 설정에서 고정한 이름이 보이지 않을 수 있고,
/dev/ttyACM0같은 포트로 연결하면 위와 같은 이유로 보정 파일을 찾지 못합니다. 로봇 창고에서 로봇을 열어 엔드이펙터 탭을 쓰는 것이 확실합니다.
Windows 판(0.1.7)에는 이 이름 문제가 없습니다
Windows 판은 USB 포트를 고정하지 않으므로 포트 목록에
COM3같은 이름이 보이고, 보정 파일은 robot id 로 찾습니다. 다만 팔을 다른 USB 구멍에 꽂으면 COM 번호가 바뀔 수 있으니 같은 구멍을 쓰세요.
2. 화면 구성
2.1. 연결 줄
팔을 꽂지 않은 상태라 포트를 찾을 수 없다는 안내가 보입니다. 저장한 팔로워 포트를 찾지 못해 목록 첫 항목인 리더 이름이 골라져 있습니다. 실제로는 팔로워 이름을 고르세요. 그림의 포트 이름은 촬영용 예시입니다.
| 칸 · 버튼 | 하는 일 |
|---|---|
| 포트 | 팔로워 팔의 포트를 고릅니다. 로봇 설정에서 고정한 이름(팔로워 · 리더)만 보이고, 탭에 들어오면 저장해 둔 팔로워 포트가 골라져 있습니다. 팔로워 이름(보통 robot id 와 같은 이름)인지 확인하세요 |
| 새로고침 | 포트 목록을 다시 읽습니다. 케이블을 꽂은 뒤 누릅니다 |
| 🔌 연결 | 팔로워에 연결합니다. 연결되면 빨간 🔌 연결 해제 로 바뀝니다 |
| Sync 확인 | 연결한 뒤 3D 와 실물 자세가 같은지 보고 누릅니다. 누르면 Sync 완료 로 바뀝니다 |
| 오른쪽 안내 글 | 지금 상태를 알려 줍니다. 예: 로봇 '<이름>' 선택됨 — Connect 를 눌러 연결. |
연결 줄은 세 하위 탭이 함께 씁니다. 한 번 연결하고 Sync 확인 을 하면 Joint Control · XYZ Control · Teaching Control 을 오가도 연결이 이어집니다.
2.2. 3D 보기
왼쪽 3D 보기에는 SO-101 팔이 그려집니다. 마우스로 끌면 시점이 돌고, 휠로 확대 · 축소합니다. Sim 에서는 내가 움직인 자세를, Real Control 에서는 실물의 자세를 따라 보여 줍니다. XYZ Control 의 Planning 중에는 목표 자세를 보여 주는 반투명한 팔(ghost)이 함께 보입니다.
2.3. Joint Control 조작 칸
연결하기 전이라 현재 위치값 이 — 로 비어 있고, 초기 포즈를 등록하기 전이라 Motion Record 탭이 흐립니다.
| 칸 | 뜻 |
|---|---|
| 현재 직교좌표 (X, Y, Z) = | 그리퍼 끝의 위치입니다. 단위는 미터(m), 기준은 팔 밑동입니다 |
| 속도/힘 | 모터의 빠르기와 힘 (5절) |
| 축 | 관절 이름 — shoulder_pan · shoulder_lift · elbow_flex · wrist_flex · wrist_roll · gripper |
| 바 | 끌어서 각도를 바꾸는 슬라이더 |
| 현재 위치값 | 모터가 읽은 값(tick). 연결해야 숫자가 들어옵니다 |
| 현재 각도 | 지금 각도(deg). 숫자를 직접 고쳐도 됩니다 |
| 키 | 그 관절을 움직이는 키보드 단축키 (3.2절) |
| 홈 포즈로 리셋 · 초기 포즈 등록 · 초기 포즈 다시 등록 | 정해 둔 자세로 돌아가는 버튼 (6절). 칸 맨 아래에 있습니다 |
3. [앱] Sim 으로 먼저 연습하기
실물을 움직이기 전에 Sim 에서 조작에 익숙해지는 것을 권합니다. Sim 은 팔을 연결하지 않아도 됩니다.
3.1. 탭 열기
- 사이드바 로봇 창고 → SO-101 로봇 카드를 누릅니다.
- 엔드이펙터 탭을 누릅니다. 처음 열 때는
엔드이펙터 준비 중입니다/처음 열 때만 시간이 걸립니다가 잠깐 뜹니다. - Joint Control → Control → Sim Control 을 고릅니다.
3.2. 슬라이더와 키보드로 움직이기
슬라이더를 끌거나 현재 각도 의 숫자를 바꾸면 3D 의 팔이 움직입니다. 키보드로도 움직일 수 있습니다.
| 관절 | 늘리기 | 줄이기 |
|---|---|---|
shoulder_pan (어깨 회전) | Q | A |
shoulder_lift (어깨 상하) | W | S |
elbow_flex (팔꿈치) | E | D |
wrist_flex (손목 굽힘) | R | F |
wrist_roll (손목 회전) | T | G |
gripper (그리퍼) | Y | H |
- 키를 누르고 있는 동안 계속 움직이고, 떼면 멈춥니다.
- 화면의 키 버튼을 마우스로 누르면 한 번에 2° 씩 움직입니다.
- 키보드로 움직이는 빠르기는 속도 슬라이더를 따릅니다 (5절).
- 다른 창을 누르는 등 이 화면에서 포커스가 벗어나면 바로 멈춥니다.
키를 눌러도 반응이 없으면
오른쪽 조작 칸을 한 번 클릭한 뒤 다시 누르세요. 모션 이름 같은 글자 입력 칸에 커서가 있으면 키가 글자로 들어갑니다.
4. 실물 연결하고 움직이기
4.1. [로봇] 준비하기
- 팔로워 팔의 USB 케이블을 PC 에 꽂고 모터 전원을 켭니다.
- 팔이 닿는 범위에서 사람 · 물건을 치웁니다.
- 팔이 넘어지지 않는 자세로 둡니다. 연결하면 그 자세를 그대로 붙잡습니다.
4.2. [앱] Real Control 을 고르고 🔌 연결
- Joint Control → Control → Real Control 탭을 고릅니다. 연결과 Sync 확인 을 마치기 전에는 Real Control 이어도 실물로 명령이 가지 않습니다.
- 포트 칸에 팔로워 이름이 골라져 있는지 확인합니다. 리더 이름이 골라져 있으면 바꿉니다.
- 🔌 연결 을 누릅니다. 안내 글이
LeRobot follower 연결 중...에서실물 자세를 시뮬레이션에 반영했습니다. 확인 후 Sync 확인을 누르세요.로 바뀝니다. - 팔에 힘(토크)이 들어가 지금 자세를 버팁니다. 3D 가 실물 자세로 바뀌고 현재 위치값 에 숫자가 들어옵니다.
이 상태에서는 Sim · Real 모두 조작 칸이 잠겨 있습니다. 실물로 명령을 보내기 전에 한 번 더 확인하는 단계가 남았습니다.
Sim Control 에서는 3D 가 실물 자세로 바뀌지 않습니다
Sim 은 실물과 따로 움직이는 연습 공간이라, 연결해도 3D 가 실물을 따라가지 않습니다. 실물과 비교할 때는 Real Control 에서 봅니다.
4.3. [앱] Sync 확인
3D 의 팔과 실물 팔을 나란히 보고 자세가 같은지 확인합니다. 같으면 Sync 확인 을 누릅니다. 안내 글이 Sync 확인됨: 시뮬레이션과 실물을 함께 제어합니다 로 바뀌고, 버튼은 Sync 완료 가 되며, 조작 칸이 풀립니다.
3D 와 실물 자세가 다르면 Sync 확인을 누르지 마세요
관절 하나가 반대로 꺾여 보이거나 크게 어긋나 있다면 보정이 맞지 않는 것입니다. 🔌 연결 해제 를 누르고 칼리브레이션을 다시 하세요.
4.4. [앱] Real Control 에서 움직이기
- Real Control 에서 슬라이더 · 키 · 숫자로 움직이면 실물이 함께 움직입니다. 3D 는 실물의 자세를 따라갑니다.
- 처음에는 키를 짧게 눌러 방향을 확인한 뒤 조금씩 움직이세요.
- 3D 로만 연습하고 싶으면 Sim Control 로 옮깁니다. 연결은 그대로 두어도 됩니다.
연결된 채로 Sim Control 에서 Real Control 로 넘어오면 안내 글에 Sim 과 실모터 각도가 다를 수 있습니다 — '초기 포즈로 리셋' 을 권장합니다. 가 뜹니다. Sim 에서 움직여 둔 3D 자세는 실물로 보내지 않고, Real Control 로 넘어오면 3D 가 실물 자세로 돌아옵니다.
팔이 목표보다 조금 처져 보여도 정상입니다
팔 무게를 받는
shoulder_lift·elbow_flex는 목표보다 1~3° 낮게 멈추곤 합니다. 앱은 마지막으로 보낸 목표를 기준으로 다음 명령을 만들기 때문에, 조작할수록 팔이 점점 내려가지는 않습니다.
Real 에서 각도 숫자를 직접 고칠 때는 화살표를 쓰세요
현재 각도 칸은 글자를 하나 칠 때마다 그 값으로 바로 움직입니다. 예를 들어
45를 치면 4° 로 갔다가 45° 로 갑니다. 칸 옆 화살표(▲ ▼)로 1° 씩 바꾸는 편이 안전합니다.
4.5. [앱] 연결 끊기
- 팔을 안전한 자세로 옮겨 둡니다 (책상에 내려놓거나 손으로 받칩니다).
- 🔌 연결 해제 를 누릅니다. 안내 글이
연결 해제로 바뀝니다.
연결이 끊기면 팔의 힘이 풀려 처지거나 떨어집니다
🔌 연결 해제 를 누를 때뿐 아니라, 다른 탭이나 사이드바 메뉴로 옮길 때도 엔드이펙터 탭은 묻지 않고 연결을 끊습니다. 편 팔은 무게 때문에 떨어질 수 있으니, 끊기 전에 팔을 내려놓거나 손으로 받치세요.
5. 속도와 힘
속도/힘 칸의 두 슬라이더는 모터에 직접 쓰는 값입니다. Joint Control 과 XYZ Control 에 같은 칸이 있습니다.
| 슬라이더 | 범위 · 기본값 | 뜻 |
|---|---|---|
| 속도 | 0~3400, 기본 1000 (u) | 모터가 목표로 가는 빠르기입니다. 0 은 ‘제한 없음’ 이라 슬라이더를 끌거나 숫자를 바꾸거나 Run · 리셋 버튼으로 한 번에 옮길 때 가장 빠릅니다. 키보드로 움직이는 빠르기도 이 값을 따릅니다 (0 이면 키보드만 정해진 빠르기로 움직입니다) |
| 힘 | 0~1000, 기본 1000 (‰, 1000 = 100%) | 모터가 낼 수 있는 힘의 한계입니다. 낮추면 힘이 약해지고, 너무 낮추면 팔이 자기 무게를 버티지 못합니다 |
- Sim 에서는 값만 바뀌고 모터에는 가지 않습니다. Real 탭으로 처음 넘어갈 때 지금 값을 모터에 보내고, 그 뒤로는 바꿀 때마다 보냅니다.
- 🔌 연결 하면 두 값이 기본값(1000 · 1000)으로 돌아갑니다. 속도를 낮추려면 연결한 뒤에 정하세요.
- 연결을 끊으면 모터 속도를 ‘제한 없음’ 으로 되돌립니다. 그래서 여기서 낮춘 속도가 텔레오퍼레이션에 남지 않습니다. 힘 은 되돌리지 않으니, 낮췄다면 끊기 전에 1000 으로 올려 두세요.
속도를 0 까지 내리면 오히려 가장 빨라집니다
천천히 움직이고 싶다면 0 이 아니라 기본값(1000)보다 작은 값을 고르세요.
6. 홈 포즈와 초기 포즈
조작 칸 맨 아래 버튼으로 정해 둔 자세에 돌아갈 수 있습니다.
| 버튼 | 하는 일 |
|---|---|
| 홈 포즈로 리셋 | 모든 관절을 0 으로 보냅니다. 팔 관절의 0° 는 보정할 때 잰 움직임 범위의 가운데로, 보통 보정을 시작할 때 맞춘 기역자 자세 근처입니다 |
| 초기 포즈 등록 | 지금 자세를 ‘초기 포즈’ 로 기억합니다. 등록하면 버튼이 초기 포즈로 리셋 으로 바뀝니다 |
| 초기 포즈로 리셋 | 기억한 초기 포즈로 돌아갑니다 |
| 초기 포즈 다시 등록 | 지금 자세로 초기 포즈를 바꿉니다 |
- Sim 에서는 3D 가 부드럽게 옮겨 가고, Real Control 에서는 실물이 속도 값대로 바로 움직입니다.
- 초기 포즈를 등록해야 Motion Record 탭이 켜집니다. 등록 전에는 탭이 흐리고
Control 탭에서 초기 포즈를 등록해야 활성화됩니다.가 보입니다. - 초기 포즈는 앱을 끄면 지워집니다. 다시 켜면 새로 등록하세요.
7. 모션 녹화 · 재생
여기서는 Joint Control 을 기준으로 설명합니다. XYZ Control (8절) · Teaching Control (9절)도 녹화 · 재생 버튼이 같습니다.
7.1. [앱] 녹화하기 (Motion Record)
- Control 에서 시작 자세를 만들고 초기 포즈 등록 을 누릅니다.
- Motion Record → Sim Motion Record(3D 만) 또는 Real Motion Record(실물도) 를 고릅니다. Real 은 연결 · Sync 확인이 필요합니다.
- 이름 칸에 모션 이름을 적고, fps(10 · 20 · 30, 기본 10)를 고릅니다.
- 필요하면 초기 포즈로 리셋 으로 시작 자세에 맞춥니다.
- ⏺ Record 를 누르고 슬라이더 · 키로 팔을 움직입니다.
- 잠깐 멈추려면 ⏸ Pause, 이어서 하려면 ⏺ Resume 을 누릅니다.
- ⏹ Stop 을 누르면 파일로 저장되고, 안내 글에
모션 N프레임 저장 (총 …초 @ …fps) → 저장: …처럼 프레임 수와 저장 경로가 보입니다.
| 이럴 때 | 보이는 것 |
|---|---|
| 이름 없이 ⏺ Record | Motion Record 이름을 정해주세요. |
| 같은 이름의 파일이 있을 때 | 이미 record 된 파일이 있습니다. → 덮어쓰기 또는 다른 이름 |
7.2. [앱] 재생하기 (Motion Replay)
- Motion Replay 탭을 고릅니다. 녹화한 모션이 하나도 없으면 탭이 흐립니다.
- 목록 위 로봇 에서 녹화한 로봇을 고르고 (안 보이면 ↻ 새로고침), 모션 카드를 누릅니다. 카드에는
N프레임 · N초 @ Nfps가 적혀 있습니다. - 재생 화면에서 ▶ 로 재생, ⏸ 로 일시정지합니다. 슬라이더로 원하는 프레임으로 옮길 수 있고, 반복 횟수나 무한 재생 을 정할 수 있습니다.
- 실물로도 재생하려면 Real 을 체크합니다. 연결 · Sync 확인이 안 되어 있으면
Real 재생: 하드웨어 미연결 또는 sync 미확인 — 시뮬만 재생됩니다.가 뜹니다. Real 을 체크하는 동안에는 안전을 위해 슬라이더로 건너뛸 수 없습니다. - ■ 정지 는 재생을 멈추고 첫 프레임으로 돌아갑니다. 🗑 삭제 는 모션 파일을 지웁니다 (되돌릴 수 없습니다).
- ← 데이터셋 선택 (Teaching Control 은 ← 모션 선택) 을 누르면 모션 목록으로 돌아갑니다. 이름과 달리 데이터셋 목록이 아닙니다.
Real 재생은 첫 프레임 자세로 바로 움직이며 시작합니다
지금 자세와 첫 프레임이 많이 다르면 팔이 그 차이만큼 빠르게 움직입니다. 재생 전에 Control 에서 초기 포즈로 리셋 으로 녹화를 시작했던 자세에 맞춰 두세요. 반복 · 무한 재생 은 끝에서 첫 자세로 곧장 돌아가고, Real 을 체크한 채 ■ 정지 를 눌러도 실물이 첫 자세로 돌아갑니다.
7.3. 녹화 파일이 저장되는 곳
모션은 JSON 파일로 저장됩니다. 관절 각도의 흐름만 담겨 있어 학습용 데이터셋은 아닙니다. 학습용 데이터는 데이터 수집에서 모읍니다.
| 화면 | 폴더 (~/.cache/physical-labs/<이름>/motion/ 아래) |
|---|---|
| Joint Control | jointcontrol/sim/ · jointcontrol/real/ |
| XYZ Control | xyzcontrol/sim/ · xyzcontrol/real/ |
| Teaching Control | posecontrol/real/ |
| (참고) 텔레오퍼레이션 | teleop/sim/ · teleop/real/ |
<이름> 은 연결한 팔로워 포트의 이름입니다. 1.6절대로 이름 칸을 비워 두었다면 robot id 와 같습니다. 연결하기 전에 Sim 에서 녹화한 모션은 default 폴더에 들어가고, Motion Replay 의 로봇 목록에도 default 로 보입니다.
xdg-open ~/.cache/physical-labs8. XYZ Control — 좌표로 움직이기
8.1. 화면
XYZ Control 의 Control 칸은 Joint Control 과 비슷하지만 버튼이 더 있습니다.
| 칸 · 버튼 | 하는 일 |
|---|---|
| 현재 직교좌표 위치 | 그리퍼 끝의 X · Y · Z 좌표 (m) |
| 속도/힘 | 5절과 같습니다 |
| Planning | 목표를 정하는 모드를 켜고 끕니다. 켜면 반투명한 목표 팔(ghost)이 보입니다 |
| Execute | ghost 가 지금 자세에서 목표까지 가는 모습을 되풀이해 보여 줍니다. 본체는 움직이지 않습니다. 미리보기 중에는 Stop 으로 바뀝니다 |
| Run | 본체를 ghost 자세로 옮깁니다. Real Control 이면 실물도 움직입니다 |
| Save · 이름: | 지금 위치를 포즈 목록에 쌓습니다. 이름: 칸에 포즈 시퀀스 이름을 적어야 켜집니다 |
| 좌표 제어 탭 | X · Y · Z 입력 칸과 후보 자세: 의 새로고침 · 다음 포즈 |
| 관절 제어 탭 | 관절별 슬라이더와 각도 칸 |
| 좌표 저장 탭 | Save 로 쌓은 포즈 목록과 리셋 · 선택 삭제 · 최종 저장 |
8.2. [앱] 목표 좌표로 이동하기
처음에는 Sim Control 에서 해 보고, 익숙해지면 연결 · Sync 확인 뒤 Real Control 에서 합니다.
- XYZ Control → Control → Sim Control (또는 Real Control) 을 고릅니다.
- Planning 을 누릅니다. 안내 글이
Planning 모드 — ghost 로봇을 움직여 타깃 자세를 설정하세요.로 바뀌고, 좌표 제어 의 X · Y · Z 칸이 켜집니다. - X · Y · Z 에 목표 좌표(m)를 적습니다. 칸마다 -1.0~1.0 m 이고, 화살표 한 번에 0.005 m(5 mm) 씩 바뀝니다.
- 후보 자세: 옆 새로고침 을 누릅니다. 앱이 그 좌표에 닿는 관절 자세를 계산해
후보 계산 완료 — 1/N을 띄우고, ghost 가 첫 후보 자세로 바뀝니다. - 다른 자세가 낫다면 다음 포즈 로 후보를 바꿉니다 (
2/N,3/N…). - Execute 로 움직임을 미리 봅니다. 다 봤으면 Stop 을 누릅니다.
- Run 을 누릅니다. 본체가 ghost 자세로 옮겨 가고, 끝나면
Run 완료 — 본체와 ghost 가 겹쳤습니다.가 뜹니다. Real Control 이면 실물도 확인 창 없이 바로 움직입니다.
좌표 방향은 3D 보기에서 값을 조금씩 바꿔 보며 확인하세요. 다 쓴 뒤 Planning 을 다시 누르면 Planning 모드가 끝납니다.
Planning 밖에서는 관절 제어 슬라이더가 바로 움직입니다
Real Control 에서 Planning 을 켜지 않은 채 관절 제어 탭의 슬라이더를 움직이면, 미리보기 없이 실물이 곧바로 움직입니다. ghost 로 미리 보려면 먼저 Planning 을 켜세요.
8.3. 후보 자세가 없을 때
SO-101 은 그리퍼를 빼면 관절이 5개라 모든 위치에 원하는 방향으로 닿을 수는 없습니다. 앱은 관절 범위를 벗어나는 자세와 그리퍼 끝이 팔 밑동 높이보다 아래로 내려가는 자세를 후보에서 뺍니다.
| 안내 글 | 뜻과 할 일 |
|---|---|
근사 자세 — 정확한 도달 불가 (5-DOF 한계) | 정확히 닿지 못해 가장 가까운 자세를 골랐습니다. ghost 를 보고 괜찮으면 그대로 씁니다 |
도달 불가능 — 좌표를 조정하세요 | 닿는 자세가 없습니다. 팔 밑동에 더 가깝거나 높은 좌표로 바꿉니다 |
Run 취소 — 해당 좌표로 IK 해가 없습니다. 좌표를 조정하세요. | 후보가 없는데 Run 을 눌렀습니다. 좌표를 바꾼 뒤 새로고침 부터 다시 합니다 |
8.4. [앱] 좌표를 모아 녹화하기
여러 목표 자세를 모아 두고 차례로 옮기며 녹화할 수 있습니다.
- 이름: 칸에 포즈 시퀀스 이름을 적습니다.
- 8.2절대로 Run 해서 팔을 옮긴 뒤 Save 를 누릅니다. 지금 위치가
Pose 1,Pose 2… 로 쌓입니다. 원하는 만큼 되풀이합니다. - 좌표 저장 탭에서 목록을 확인하고, 필요 없는 것은 선택 삭제, 처음부터 다시 하려면 리셋 합니다.
- 최종 저장 을 누릅니다. 목록이 확정되어 Motion Record 에서 쓸 수 있게 됩니다.
- Motion Record → Sim Motion Record 또는 Real Motion Record → 이름을 적고 ⏺ Record 를 누릅니다.
- 왼쪽
저장된 좌표 (index 순)목록에서 포즈를 고르고 아래 ▶ Run 을 누르는 일을 되풀이합니다. - ⏹ Stop 으로 녹화를 저장합니다.
- Sim Control 에서 Save 한 포즈와 Real Control 에서 Save 한 포즈는 따로 쌓입니다.
- 최종 저장 은 목록을 확정할 뿐 파일로 남기지 않습니다. 앱을 끄면 포즈 목록은 사라지고, 파일로 남는 것은 ⏹ Stop 으로 저장한 모션뿐입니다.
9. Teaching Control — 손으로 가르치기
Teaching Control 은 팔을 손으로 직접 잡아 자세를 가르치는 화면입니다. 실물 전용이라 🔌 연결 과 Sync 확인 을 먼저 해야 합니다. 그 전에는 로봇을 연결하세요 — 상단의 🔌 연결 후 Sync 확인을 누르면 활성화됩니다. 안내가 보이고 버튼이 잠겨 있습니다.
9.1. [앱] 자유 이동으로 포즈 저장하기
- [로봇] 팔을 한 손으로 단단히 잡습니다.
- [앱] 🖐 자유 이동 시작 (토크 해제) 를 누르면 확인 창
자유 이동 (토크 해제)이 뜹니다. 그리퍼를 포함한 모든 모터의 힘이 풀린다는 안내를 읽고 Yes 를 누릅니다. - [앱] 버튼이 빨간 🖐 자유 이동 종료 (토크 켜기) 로 바뀌고
토크 해제됨 — 손으로 로봇을 움직여 포즈를 잡으세요.가 뜹니다. 이제 손으로 팔을 움직이면 3D 가 따라옵니다. - [앱] 포즈 시퀀스 이름 칸에 이름(예:
pick_and_place)을 적습니다. - [로봇] 원하는 자세를 만들고, [앱] 📌 포즈 저장 을 누릅니다. 자세마다 되풀이합니다.
- [앱] 다 했으면 팔을 잡은 채 🖐 자유 이동 종료 (토크 켜기) 를 누릅니다.
토크 활성화 — 현재 자세를 유지합니다.가 뜨고 그 자리에서 힘이 들어옵니다. - [앱] 포즈 목록을 확인하고 최종 저장 을 누릅니다 (필요 없는 포즈는 선택 삭제, 처음부터는 리셋).
자유 이동 중에는 팔을 놓지 마세요
모든 모터의 힘이 풀려 팔이 무게 때문에 떨어집니다. 다른 하위 탭으로 옮기면 앱이 자유 이동을 끝내고 힘을 다시 켭니다.
9.2. [앱] 저장한 포즈 실행 · 녹화하기
- Motion Record 탭으로 갑니다.
저장된 포즈 (index 순)에 저장한 포즈가 보입니다. - 포즈 하나를 고르고 ▶ Run (선택 포즈) 를 누르면 실물이 그 자세로 옮겨 갑니다. ▶ 전체 실행 (순차) 는 모든 포즈를 순서대로 실행합니다.
- 녹화하려면 이름을 적고 ⏺ Record → ▶ 전체 실행 (순차) (또는 포즈를 하나씩 ▶ Run) → ⏹ Stop 을 누릅니다.
- 녹화한 모션은 Motion Replay 에서 7.2절과 같이 재생합니다.
자유 이동이 켜진 채로 실행 · 녹화 · 재생하려 하면 자유 이동 모드가 켜져 있습니다. 토크를 다시 켜고 계속할까요? 가 뜹니다. Yes 를 누르면 힘만 다시 켜지므로, 팔 자세를 확인한 뒤 버튼을 한 번 더 누르세요.
10. 문제 해결
| 증상 | 확인할 것 |
|---|---|
팔로워 보정 정보가 없습니다. '칼리브레이션' 탭에서 먼저 보정을 진행해 주세요. | 팔로워 보정을 아직 안 했다면 칼리브레이션부터 합니다. 보정을 했는데도 뜬다면 포트 이름이 robot id 와 다른 것입니다 (1.6절). 포트 칸에 리더 이름이 골라져 있어도 이렇게 뜹니다 |
포트 '<포트>' 를 찾을 수 없음 — 케이블 연결 후 새로고침하세요. | 팔로워 USB 와 모터 전원을 확인하고 새로고침 을 누릅니다. 로봇을 막 저장했다면 USB 를 한 번 뽑았다 꽂습니다 |
실물 로봇 포트를 선택하세요. | 포트 목록이 비어 있습니다 (포트 없음). 팔로워 USB 가 꽂혀 있는지, 로봇 설정에서 로봇 저장 까지 했는지 확인합니다 |
Could not connect on port '…' | 포트가 맞는지, 케이블 · 전원이 꽂혀 있는지 봅니다. 그래도 안 되면 시리얼 포트 권한(dialout)을 확인합니다 → 문제 해결 |
| 포트 목록에 예전 이름이 보인다 | 엔드이펙터 탭을 먼저 열어 둔 뒤 로봇 설정을 다시 저장한 경우입니다. 사이드바 로봇 창고 에서 로봇을 다시 엽니다 |
| 연결했는데 슬라이더 · 키가 안 움직인다 | Sync 확인 을 눌렀는지 봅니다. 그 전에는 조작 칸이 잠겨 있습니다 |
| 3D 는 움직이는데 실물이 가만히 있다 | Sim Control 에 있는지 봅니다. 실물은 Real Control · Real Motion Record 에서만 움직입니다 |
| 키를 눌러도 반응이 없다 | 오른쪽 조작 칸을 한 번 클릭합니다. 글자 입력 칸에 커서가 있으면 키가 글자로 들어갑니다 |
| 연결 직후 3D 와 실물 자세가 다르다 | Sync 확인 을 누르지 말고 연결을 끊은 뒤 보정을 다시 합니다 |
| 팔이 목표보다 조금 처져 있다 | 무게를 받는 관절은 1~3° 처지는 것이 정상입니다 (4.4절) |
| 생각보다 너무 빠르게 움직인다 | 속도 가 0(제한 없음)이 아닌지 봅니다. 기본값 1000 보다 낮춰 씁니다 |
| Motion Record 탭이 흐리다 | Control 에서 초기 포즈 등록 을 먼저 누릅니다 |
| Motion Replay 탭이 흐리다 | 녹화한 모션이 없습니다. Motion Record 에서 먼저 녹화합니다 |
| Real 을 체크했는데 3D 만 재생된다 | Real 재생: 하드웨어 미연결 또는 sync 미확인 이면 🔌 연결 · Sync 확인 을 먼저 합니다 |
도달 불가능 — 좌표를 조정하세요 | 닿지 않는 좌표입니다. 팔 밑동에 가깝거나 높은 좌표로 바꿉니다 (8.3절) |
N번 모터에서 응답이 없어 통신에 실패했습니다. 같은 모터 오류 | 오류 창에 흔한 원인이 순서대로 나옵니다. 모터 전원 · 배선, 다른 탭이나 터미널이 같은 포트를 쓰는지, 모터 ID 가 겹치지 않는지 봅니다 → 문제 해결 |
| 엔드이펙터 탭이 회색이라 눌리지 않는다 | SO-102 로봇입니다. SO-102 는 아직 엔드이펙터를 지원하지 않습니다 |
이 로봇(ROS2 LeKiwi)에서는 아직 지원하지 않습니다. | 0.2.0 재배포(2026-11-01 저녁) 전 판입니다. sudo apt install --reinstall ./ 로 다시 설치합니다 |
| 탭을 옮겼더니 팔이 떨어졌다 | 엔드이펙터 탭은 다른 탭 · 사이드바로 옮기면 묻지 않고 연결을 끊어 힘이 풀립니다. 옮기기 전에 팔을 내려놓습니다 |
그 밖의 문제는 문제 해결에 모았습니다.
11. 정리
- 엔드이펙터 탭은 리더 팔 없이 화면에서 팔로워를 움직입니다. Joint Control 은 관절 각도, XYZ Control 은 그리퍼 끝 좌표, Teaching Control 은 손으로 가르친 자세로 움직입니다.
- 실물은 🔌 연결 → Sync 확인 을 마친 뒤 Real 이 붙은 탭에서만 움직이고, 움직일 때 확인 창은 없습니다. 충돌은 검사하지 않으니 주변을 비웁니다.
- 속도 0 은 ‘제한 없음’ 이라 가장 빠릅니다. 천천히 하려면 1000 보다 낮은 값을 씁니다.
- 초기 포즈를 등록해야 녹화할 수 있고, 녹화한 모션은 Motion Replay 에서 Sim 이나 Real 로 재생합니다.
- 지금 Ubuntu 판에서는 로봇 설정의
follower arm:이름 칸을 비워 두어야 보정 파일을 찾습니다. - 연결을 끊거나 탭을 옮기면 힘이 풀려 팔이 처집니다. 먼저 팔을 내려놓으세요.

