기능 패키지 설치

Physical Labs 는 처음 설치할 때 로그인 · 모터 셋업 · 로봇 설정에 필요한 기본 구성만 넣습니다. 칼리브레이션 · 텔레오퍼레이션 · 데이터 · 훈련처럼 큰 라이브러리가 필요한 기능은 그 기능을 처음 열 때 화면에 뜨는 설치 카드로 한 번만 설치합니다. 이 페이지에서는 기능마다 무엇이 필요한지, 설치 카드와 관리자 비밀번호 창을 어떻게 다루는지, GPU 로 학습하려면 PyTorch 를 어떻게 바꾸는지 안내합니다.

학습 목표

  • 기능 패키지를 나눠서 설치하는 이유를 설명할 수 있다.
  • 기능마다 필요한 패키지와 내려받는 크기를 표에서 찾을 수 있다.
  • 설치 카드로 패키지를 설치하고, 관리자 비밀번호 창에 답할 수 있다.
  • 설정 › 기능 패키지 에서 모든 기능을 한 번에 미리 설치할 수 있다.
  • NVIDIA GPU 가 있는 PC 에서 GPU 버전 PyTorch 로 바꿀 수 있다.

1. 기능 패키지란?

1.1. 왜 나눠서 설치할까?

모터에 ID 를 붙이거나 로봇을 등록만 하는 PC 에는 학습용 라이브러리가 필요 없습니다. 그래서 앱 설치는 기본 구성만으로 2~3분 안에 끝내고, 다른 기능은 쓰기 시작할 때 더합니다.

1.2. 패키지 네 가지

크기와 시간은 Ubuntu 판 앱 화면에 나오는 값 그대로입니다 (Windows 판은 로봇 제어 패키지와 GPU 버전 PyTorch 의 값이 다릅니다). 실제 시간은 인터넷 속도에 따라 다릅니다.

패키지하는 일 · 들어 있는 것내려받기 · 설치 후예상 시간
기본 구성 (항상 설치)로그인 · 모터 셋업 · 로봇 설정 — 화면(PyQt6) · PyTorch(CPU) · 카메라(OpenCV) · LeKiwi 통신(pyzmq)약 526MB · 약 1.7GB앱을 설치할 때 함께 (약 2~3분)
로봇 제어 패키지SO-101 · LeKiwi 제어와 역기구학 — lerobot · placo · pybullet · python-fcl · ruckig약 225MB · 약 900MB약 2분
데이터 패키지데이터셋 녹화 · 재생 · 편집 — lerobot 데이터셋(datasets · pandas · pyarrow) · 영상 코덱(av · torchcodec)약 113MB · 약 380MB1분 이내
학습 패키지모델 학습 실행 · 학습 기록 — accelerate · wandb약 33MB · 약 110MB1분 이내

뒤의 패키지는 앞의 패키지 위에 올라갑니다

순서는 기본 구성 → 로봇 제어 → 데이터 → 학습입니다. 학습 패키지를 설치하면 아직 없는 로봇 제어 · 데이터 패키지도 함께 설치됩니다.

1.3. 기능별로 필요한 패키지

맨 오른쪽 칸은 아무 패키지도 없는 PC 에서 처음 설치할 때의 값입니다. 이미 설치한 패키지는 다시 받지 않습니다. 예를 들어 칼리브레이션을 먼저 설치했다면, 텔레오퍼레이션을 열 때는 데이터 패키지(약 113MB)만 받습니다.

기능처음 여는 곳 [앱]필요한 패키지내려받기 · 예상 시간
로그인 · 모터 셋업 · 로봇 설정사이드바 모터 셋업, 로봇의 로봇 설정 탭기본 구성설치 필요 없음
칼리브레이션칼리브레이션 탭로봇 제어약 225MB · 약 2분
엔드이펙터엔드이펙터 탭, 위쪽 막대의 도구 메뉴(☰) › End Effector Control로봇 제어약 225MB · 약 2분
텔레오퍼레이션텔레오퍼레이션 탭로봇 제어 + 데이터약 338MB · 약 3분
데이터데이터 탭로봇 제어 + 데이터약 338MB · 약 3분
추론추론 탭로봇 제어 + 데이터약 338MB · 약 3분
훈련훈련 탭로봇 제어 + 데이터 + 학습약 371MB · 약 3분
데이터셋 재생·편집사이드바 데이터셋 창고 에서 데이터셋 열기 · 병합 · 업로드 · 내려받기로봇 제어 + 데이터약 338MB · 약 3분
워크스페이스사이드바 워크스페이스 › 카드 › 환경 준비의 설치로봇 제어 + 데이터약 338MB · 약 3분

2. 설치 카드로 설치하기

2.1. [앱] 설치가 필요한 탭 알아보기

로봇 작업 화면 위쪽의 탭 줄에서, 설치가 필요한 탭은 이름 옆에 연보라 동그라미 안의 아래 화살표 아이콘이 붙어 있습니다. 마우스를 올리면 처음 열 때 추가 설치가 필요합니다 (로봇 제어 패키지 · 데이터 패키지) 처럼 아직 없는 패키지가 나옵니다. 필요한 패키지를 다 설치하면 아이콘이 사라집니다.

2.2. [앱] 설치 카드 읽기

아이콘이 붙은 탭을 열면 원래 화면 대신 설치 카드가 나옵니다.

텔레오퍼레이션 탭의 설치 카드 — 로봇 제어 패키지와 데이터 패키지 두 줄, 합계 약 338MB · 약 3분, 설치하기와 모든 기능 한 번에 설치 버튼

텔레오퍼레이션 탭을 처음 열었을 때의 설치 카드입니다.

부분화면 글자 (텔레오퍼레이션 예)뜻
제목텔레오퍼레이션을 사용하려면 추가 설치가 필요합니다이 탭에 무엇이 모자라는지 알려 줍니다.
부제처음 한 번만 설치하면 됩니다. 설치가 끝나면 이 화면이 바로 열립니다.앱을 다시 켤 필요가 없습니다.
패키지 줄로봇 제어 패키지 · 내려받기 약 225MB · 설치 후 약 900MB설치할 패키지마다 한 줄씩, 크기와 들어 있는 것을 보여 줍니다.
합계합계: 내려받기 약 338MB · 예상 시간 약 3분 (인터넷 속도에 따라 다릅니다)이번에 받을 전체 크기와 시간입니다.
쓸 수 있는 기능설치하면 쓸 수 있는 기능: 칼리브레이션 · 엔드이펙터 · …같은 패키지로 함께 열리는 기능들입니다.
안내인터넷 연결이 필요합니다. … 설치 중에도 다른 탭은 그대로 쓸 수 있습니다.Ubuntu(.deb) 에서는 가운데에 설치할 때 관리자(시스템) 비밀번호를 한 번 물어봅니다. 가 더 붙습니다 (그림에는 없습니다).
버튼설치하기 · 모든 기능 한 번에 설치 (내려받기 약 371MB)아래 2.3절.
로그▸ 설치 로그 보기설치 중에 나오는 자세한 기록을 펼칩니다.

두 버튼의 차이는 이렇습니다.

2.3. 설치 순서

  1. [앱] 설치 카드에서 설치하기 (또는 모든 기능 한 번에 설치) 를 누릅니다.
  2. [PC] Ubuntu 에서는 관리자 비밀번호 창이 뜹니다. 비밀번호를 입력합니다 (2.4절).
  3. [앱] 진행 막대가 움직이는 동안 기다립니다. 그동안 다른 탭을 써도 됩니다 (2.5절).
  4. [앱] 설치가 완료되었습니다. 가 나오면 카드가 그 탭의 원래 화면으로 바뀝니다. 앱을 다시 켤 필요는 없습니다.

2.4. [PC] 관리자 비밀번호 창 (Ubuntu)

Ubuntu 에 .deb 로 설치한 앱은 전용 파이썬 환경(/opt/physical-labs/venv)이 시스템(관리자) 소유입니다. 그래서 패키지를 설치할 때마다 Ubuntu 가 관리자 인증 창을 띄웁니다. sudo 에 쓰는 비밀번호, 곧 이 PC 에 로그인할 때 쓰는 비밀번호를 입력합니다. 이 창은 앱이 아니라 Ubuntu 가 띄우는 것이라 문구가 PC 마다 조금 다를 수 있습니다. 이때 카드의 진행 글은 관리자 비밀번호를 입력해 주세요… 입니다.

Windows 판은 비밀번호를 묻지 않습니다

Windows 판은 앱이 내 계정 폴더에 설치되어 있어서, 기능 패키지를 설치할 때 관리자 비밀번호 창이 뜨지 않습니다. 나머지 과정은 같습니다.

2.5. [앱] 진행 화면

설치가 시작되면 버튼 자리에 진행 표시가 나옵니다.

설치는 앱 전체가 맡아 하므로 다른 탭이나 화면으로 옮겨도 계속됩니다. 같은 패키지가 필요한 다른 탭의 설치 카드에도 같은 진행 표시가 나오고, 관계없는 카드에는 다른 기능 패키지를 설치하는 중입니다… 끝나면 이어서 설치할 수 있습니다. 가 보입니다.

2.6. [앱] 설치가 끝나면

설치가 끝나면 잠깐 새 기능을 준비하는 중입니다 창(방금 설치한 라이브러리를 불러오고 있습니다)이 뜨고, 설치가 완료되었습니다. 가 나온 뒤 카드가 그 탭의 화면으로 바뀝니다.

드물게 이미 불러온 라이브러리가 바뀌어 다시 시작해야 할 때가 있습니다. 이때는 아래 같은 글과 함께 지금 다시 시작 버튼이 나옵니다. 눌러서 앱을 다시 켭니다.

앱을 다시 켤 때도 인터넷이 필요합니다

앱은 켤 때마다 구글 로그인을 확인합니다. 노트북이 로봇 AP 처럼 인터넷이 없는 와이파이에 붙어 있다면, 인터넷이 되는 와이파이로 바꾼 뒤에 다시 시작하세요 (설치와 첫 실행 5.2절).


3. 탭이 아닌 곳에서 뜨는 설치 창

탭이 아닌 곳에서 패키지가 필요한 일을 하면 설치 카드가 창으로 뜹니다. 창 제목은 <기능> — 추가 설치 입니다.

여는 곳 [앱]창 제목
사이드바 데이터셋 창고 에서 데이터셋 열기 · 병합 · 업로드 · 내려받기데이터셋 재생·편집 — 추가 설치
사이드바 워크스페이스 › 카드 › 환경 준비의 설치워크스페이스 — 추가 설치
위쪽 막대의 도구 메뉴(☰) › End Effector Control엔드이펙터 — 추가 설치

설치 창 — 설치 카드와 같은 내용에 '이 창을 닫아도 설치는 계속됩니다' 안내와 오른쪽 아래 닫기 버튼이 있다

창으로 뜬 설치 카드의 예입니다 (그림은 텔레오퍼레이션 카드를 창으로 띄운 것). 실제 창의 제목에는 위 표의 기능 이름이 들어가고, 탭의 카드와 달리 안내 끝이 이 창을 닫아도 설치는 계속됩니다. 이며 오른쪽 아래에 닫기 버튼이 있습니다.


4. 설정 › 기능 패키지에서 미리 설치하기

현장에 가기 전이나 여러 기능을 한꺼번에 준비할 때는 설정에서 미리 설치합니다. 사이드바 맨 아래의 계정 버튼을 누르고 설정 › 기능 패키지 를 고릅니다.

설정 › 기능 패키지 화면 — 기본 구성 · 로봇 제어 패키지 · 데이터 패키지 · 학습 패키지 네 줄이 모두 설치됨으로 표시되고, 아래에 PyTorch 버전이 보인다

모든 패키지가 설치된 PC 의 화면입니다. 새로 설치한 PC 에서는 설치 필요 표시와 설치 버튼, 모든 기능 한 번에 설치 버튼이 함께 보입니다.

부분설명
패키지 줄이름, <요약> — <들어 있는 것>, 내려받기 … · 설치 후 … 가 보입니다.
상태 표시설치됨 · 설치 필요 · 업데이트 필요 (8절)
설치 · 업데이트 버튼기능 패키지 설치 창이 열리고, 창의 설치하기 를 눌러야 설치가 시작됩니다. 앞의 패키지가 없으면 함께 설치합니다 — 예를 들어 새 PC 에서 학습 패키지의 설치 를 누르면 창 안의 제목이 로봇 제어 패키지 · 데이터 패키지 · 학습 패키지 설치 입니다. 이미 설치된 줄에는 버튼이 없습니다.
모든 기능 한 번에 설치 (내려받기 약 371MB)아직 없는 패키지를 모두 설치합니다. 이것도 기능 패키지 설치 창의 설치하기 로 시작합니다. 괄호 안 크기는 아직 없는 패키지만 더한 값이고, 다 설치되어 있으면 버튼이 보이지 않습니다. 버튼 아래에는 한 번에 설치하면 관리자 비밀번호를 한 번만 입력합니다. 오프라인 현장에 가기 전에 미리 받아 두세요. 가 보입니다.
PyTorch지금 쓰는 PyTorch 가 CPU 버전인지 GPU 버전인지 보여 줍니다. CPU 버전이면 CPU 버전 사용 중 — 2.11.0+cpu 와 함께 NVIDIA GPU 가 있다면 훈련 탭 › 환경 진단에서 GPU 버전을 설치할 수 있습니다 (GPU 가 인식될 때만 안내됩니다). 가 나옵니다 (7절).

설치하는 동안에는 이 화면 아래에 설치 진행 중: <진행 글> 이 나옵니다.

인터넷이 없는 곳에 가기 전에 미리 받아 두세요

수업 · 시연처럼 로봇 AP(인터넷 없음)로 일하는 날에는, 전날 인터넷이 되는 곳에서 모든 기능 한 번에 설치 → 설치하기 를 눌러 두면 현장에서 설치 카드에 막히지 않습니다. 약 3분, 관리자 비밀번호 한 번이면 됩니다. 워크스페이스의 YOLO 나 훈련 탭의 모델 라이브러리처럼 따로 설치하는 것도 쓸 예정이면 미리 설치해 둡니다.


5. 설치는 한 번에 하나씩

앱 전체에서 라이브러리 설치는 한 번에 하나만 진행됩니다. 설치 중에 다른 설치를 시작하면 이런 글이 나옵니다. 앞의 설치가 끝난 뒤 다시 누르세요.

글뜻
다른 기능 패키지를 설치하는 중입니다. 끝난 뒤 다시 시도해 주세요.다른 탭 · 창에서 시작한 기능 패키지 설치가 진행 중입니다.
다른 라이브러리 설치가 진행 중입니다. 끝난 뒤 다시 시도해 주세요.훈련 탭의 모델 라이브러리나 워크스페이스의 YOLO 처럼, 기능 패키지가 아닌 설치가 진행 중입니다.

6. 설치 중에 앱을 닫으면

설치 중에 ✕ 를 누르거나 창을 닫으면 설치 진행 중 창이 먼저 뜹니다.

기능 패키지를 설치하는 중입니다. / 지금 종료하면 설치가 중간에 끊겨 일부 라이브러리만 바뀐 채 남을 수 있습니다 (그 기능을 다시 열어 설치하면 복구됩니다). / 설치가 끝난 뒤 자동으로 종료할까요?

버튼하는 일
설치가 끝나면 종료 (기본, Enter)작은 창 설치 마무리 중 이 설치가 끝나면 앱을 자동으로 종료합니다. 를 보여 주며 기다리다가, 설치가 끝나면 앱을 끕니다. 그 창의 종료 취소 를 누르면 앱을 계속 씁니다.
지금 종료바로 끕니다. 설치가 중간에 끊겨 일부 라이브러리만 바뀐 채 남을 수 있습니다. 다음에 그 기능을 다시 열어 설치하면 복구됩니다.
취소 (Esc)끄지 않고 돌아갑니다.

앱을 끄면 설치도 멈춥니다

관리자 비밀번호를 넣고 시작한 설치도 앱이 꺼지면 중간에 멈춥니다. 앱을 꺼야 한다면 설치가 끝나면 종료 를 고르세요. 설치 창을 닫는 것은 괜찮습니다 — 창만 닫히고 설치는 계속됩니다.

설치 중에는 앱 다시 시작도 막힙니다. 예를 들어 설치 중에 설정 에서 화면 배율을 저장하면, 값은 저장되지만 앱 다시 시작 창에 라이브러리를 설치하는 중입니다. / 설치가 끝난 뒤 다시 시작해 주세요. 가 나오고 앱은 다시 시작하지 않습니다. 설치가 끝난 뒤 앱을 다시 켜면 적용됩니다.


7. GPU 버전 PyTorch 로 바꾸기

기본 구성에는 CPU 버전 PyTorch 가 들어 있습니다. CPU 로도 학습은 되지만 매우 느립니다. NVIDIA GPU 가 있는 PC 라면 훈련 탭 › 환경 진단 에서 GPU 버전으로 바꿉니다. 여기서는 조건과 순서만 짧게 정리하고, 화면 · 안내 띠마다의 뜻은 훈련 2.2절에서 설명합니다.

7.1. 조건

조건확인하는 법
NVIDIA GPU터미널에서 nvidia-smi 를 실행하면 GPU 이름이 나옵니다.
NVIDIA 드라이버 570 이상nvidia-smi 결과의 Driver Version 이 570 이상이어야 합니다 (GPU 버전 PyTorch 가 CUDA 12.8 을 씁니다).
Ubuntu 24.04 의 .deb 판이 설명서대로 설치했다면 됩니다. Windows 판은 아래 정보 상자를 봅니다.
학습 패키지훈련 탭을 처음 열 때 설치 카드로 설치합니다 (아래 1단계).
인터넷 · 저장 공간약 4.0GB 를 내려받고, 설치하면 약 5.9GB 를 차지합니다. 설치를 시작할 때 /opt 가 있는 디스크에 약 11.8GB(내려받기 + 설치 공간에 여유분)가 비어 있는지 확인하므로 그만큼 비워 둡니다.

7.2. 바꾸는 순서 (요약)

  1. [앱] 로봇 창고 에서 로봇을 골라 훈련 탭을 엽니다. 처음이면 설치 카드의 설치하기 로 학습에 필요한 패키지를 먼저 설치합니다.
  2. [앱] 하위 탭 환경 진단 의 안내 띠에서 GPU 버전 PyTorch 설치 → GPU 버전 설치하기 를 누르고, [PC] 관리자 비밀번호를 넣습니다. 약 15분 걸리고, 창을 닫아도 설치는 계속됩니다.
  3. [앱] 끝나면 지금 다시 시작 을 누릅니다 (인터넷이 될 때). 다시 켠 뒤 설정 › 기능 패키지 의 PyTorch 줄이 GPU(CUDA) 버전 사용 중 이면 끝입니다.

앱을 업데이트해도 GPU 버전 PyTorch 는 CPU 버전으로 돌아가지 않습니다.

Windows 판

설치 프로그램이 NVIDIA GPU 와 드라이버 570 이상을 찾으면 처음부터 GPU 버전 PyTorch 를 설치합니다. 그렇지 않았다면 훈련 탭 › 환경 진단 에서 같은 방법으로 바꿀 수 있습니다.


8. 앱을 업데이트한 뒤 ‘업데이트하기’ 가 보이면

앱을 새 버전으로 업데이트하면, 설치되어 있던 기능 패키지도 보통 업데이트 과정에서 함께 새 버전으로 맞춰집니다. 그러지 못한 패키지가 있으면 그 기능을 열 때 카드가 이렇게 바뀝니다.

업데이트하기 를 누르면 설치와 같은 과정으로 진행됩니다. 설정 › 기능 패키지 에서는 그 줄이 업데이트 필요 로 보이고, 업데이트 버튼으로 같은 일을 합니다.


9. 문제 해결

설치에 실패하면 카드에 원인과 할 일이 나오고, 버튼이 다시 시도 로 바뀌며, 설치 로그가 저절로 펼쳐집니다. Ubuntu 에서는 직접 실행할 수 있는 명령과 명령 복사 버튼도 함께 나옵니다.

증상확인할 것
인터넷에 연결할 수 없습니다 (pypi.org). 연결을 확인한 뒤 다시 시도해 주세요.PC 가 인터넷에 붙어 있는지 확인합니다. 노트북이 로봇 AP(인터넷 없음)에 붙어 있다면 공유기 와이파이로 바꾼 뒤 다시 누릅니다.
인터넷 연결 문제로 설치하지 못했습니다.회사 · 학교 방화벽이나 프록시를 확인합니다. 프록시가 필요한 망이면, 프록시 환경 변수(https_proxy)를 설정한 터미널에서 physical-labs 로 앱을 켜고 다시 설치합니다. 주소에 계정 · 비밀번호가 들어간 프록시는 앱이 넘기지 않으므로, 실패 화면의 명령을 명령 복사 로 복사한 뒤 끝에 --proxy <프록시 주소> 를 붙여 터미널에서 실행하고, 앱을 다시 시작합니다.
디스크 여유 공간이 부족합니다 — 필요 … · 남은 공간 … 또는 디스크 공간이 부족해 설치하지 못했습니다./opt 가 있는 디스크의 공간을 비운 뒤 다시 시도합니다.
관리자 인증이 취소되었거나 실패했습니다.다시 시도 를 누르고 관리자 비밀번호 창에 비밀번호를 정확히 입력합니다.
설치 위치에 쓰기 권한이 없어 설치하지 못했습니다.화면의 명령(sudo /opt/physical-labs/venv/bin/python3 -m pip install …)을 명령 복사 로 복사해 터미널에서 실행한 뒤, 앱을 다시 시작합니다.
다른 기능 패키지를 설치하는 중입니다… · 다른 라이브러리 설치가 진행 중입니다…앞의 설치가 끝날 때까지 기다린 뒤 다시 누릅니다 (5절).
설치할 패키지를 찾지 못했습니다.인터넷 연결을 확인합니다. 계속되면 설치 로그를 RoboSEasy 에 보내 주세요.
설치 중 오류가 발생했습니다 (종료 코드 …).▸ 설치 로그 보기 에서 마지막 부분을 확인하고 다시 시도 합니다. 같은 오류가 계속되면 설치 로그를 RoboSEasy 에 보내 주세요.
설치 뒤 라이브러리를 불러오지 못했습니다 경고가 뜬다영상 디코더(FFmpeg)가 없을 때 흔히 생깁니다. 터미널에서 sudo apt install ffmpeg 를 실행한 뒤 앱을 다시 시작합니다.
중단 을 눌렀는데 멈추지 않는다Ubuntu 에서 관리자 권한으로 진행되는 설치는 중단이 듣지 않을 수 있습니다. 끝날 때까지 기다리면 성공으로 처리됩니다.
지금 종료 로 껐더니 기능이 이상하다설치가 중간에 끊긴 것입니다. 그 기능을 다시 열어 설치하면 복구됩니다.
환경 진단에 GPU 버전 PyTorch 설치 버튼이 없다훈련 2.2절의 안내 띠 표를 확인합니다. 드라이버가 570 미만이거나 GPU 가 인식되지 않으면 버튼이 나오지 않습니다.

10. 정리

다음 단계로 기본 구성만으로 바로 쓸 수 있는 모터 셋업과 로봇 설정을 진행하세요.