설치

Pinkrab 을 쓰려면 Python 3.12 이상과 ROS 2 Jazzy 가 필요한데, 설치 방법은 ROS 를 어디서 받느냐에 따라 달라집니다. macOS 용 ROS 는 운영체제 패키지로 나오지 않아서 RoboStack 의 conda 패키지로 설치하고, 이 경우 ROS 와 LeRobot, MuJoCo 가 Python 인터프리터 하나에 함께 들어갑니다. Ubuntu 에서는 ROS 를 apt 로 설치하는데, 이 ROS 는 시스템의 Python 3.12 로 빌드되어 있으므로 Pinkrab 패키지도 그 Python 으로 만든 venv 에 설치합니다.

아래 탭에서 운영체제를 한 번 고르면 페이지의 모든 단계가 그 운영체제 기준으로 바뀝니다.

사전 준비

macOS

RoboStack 은 ROS 2 Jazzy 를 conda 패키지로 배포합니다. 이 패키지를 설치하려면 conda 가 있어야 하는데, Miniforge 를 설치하면 conda 와 함께 더 빠른 설치 도구인 mamba 도 깔립니다.

brew install miniforge
conda init "$(basename "$SHELL")"

설치가 끝나면 새 터미널을 열어야 셸에서 conda 명령을 쓸 수 있습니다.

Ubuntu

Ubuntu 24.04 에 ROS 2 Jazzy 를 apt 로 설치한 상태에서 시작하고, ROS 패키지는 ros-jazzy-ros-base 만 있으면 됩니다. 그다음 빌드에 필요한 도구를 설치합니다.

sudo apt install -y python3.12-venv python3-rosdep python3-colcon-common-extensions \
  ros-jazzy-rmw-cyclonedds-cpp
sudo rosdep init
rosdep update

Python 환경

macOS

requirements/environment.yml 로 RoboStack 환경을 만듭니다. 이 환경에는 robostack-jazzy 채널의 ROS 2 Jazzy 와 colcon, LeRobot, MuJoCo 가 Python 3.12 하나로 들어 있고, Pinkrab 패키지는 이 환경에 editable 모드로 설치합니다.

git clone https://github.com/woolimi/pinkrab.git
cd pinkrab
mamba env create -f requirements/environment.yml
mamba activate pinkrab
pip install -e src/pinkrab_core -e src/pinkrab_cli -e src/pinkrab_mujoco \
  -e src/pinkrab_studio -e src/pinkrab_umi -e src/pinkrab_policy -e lerobot-plugin

Ubuntu

rclpy 는 /usr/bin/python3.12 에 맞춰 컴파일된 C extension 이라 다른 Python 에서는 불러올 수 없습니다. 그래서 venv 도 이 Python 으로 만들고, ROS 의 rclpy 가 venv 안에서도 보이도록 --system-site-packages 옵션을 붙입니다. scripts/setup.sh 가 이 venv 를 만들고 requirements/lock/linux.txt 의 패키지와 Pinkrab 패키지를 설치한 뒤 실제로 설치된 결과를 출력하며, 여러 번 실행해도 문제없습니다.

git clone https://github.com/woolimi/pinkrab.git
cd pinkrab
./scripts/setup.sh

새 셸을 열 때마다 ROS 를 먼저 source 하고 venv 를 나중에 활성화합니다. 이 순서여야 같은 이름의 패키지가 ROS 와 venv 양쪽에 있을 때 venv 쪽이 쓰입니다.

source /opt/ros/jazzy/setup.bash
source .venv/bin/activate

ROS 패키지

macOS

RoboStack 환경에는 ROS 의존성이 이미 모두 들어 있어서 rosdep 은 쓰지 않습니다. 빌드할 때는 CMake 에 환경의 Python 과 NumPy 경로를 직접 알려 주는데, 경로를 주지 않으면 CMake 가 다른 python3 를 먼저 찾아 pinkrab_interfaces 빌드가 실패할 수 있습니다.

colcon build --symlink-install --cmake-args \
  -DPython3_EXECUTABLE="$CONDA_PREFIX/bin/python3" \
  -DPython3_NumPy_INCLUDE_DIRS="$CONDA_PREFIX/lib/python3.12/site-packages/numpy/_core/include"
source install/setup.zsh

셸이 bash 라면 마지막 줄에서 install/setup.bash 를 source 합니다.

Ubuntu

rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install
source install/setup.bash

--symlink-install 로 빌드해 두면 Python 코드를 고친 뒤 다시 빌드하지 않아도 바로 반영됩니다. 새 파일이나 entry point, launch 파일을 추가했을 때만 다시 빌드합니다.

장치 권한

macOS

서보 보드와 카메라는 별도 설정 없이 열립니다. 풋 페달은 root 권한이 있어야 열리기 때문에 studio 가 sudo -n 으로 실행하는데, 이때 비밀번호를 묻지 않도록 sudoers 에 허용 규칙을 한 줄 넣어 둡니다. 아래 명령은 conda 환경을 활성화한 상태에서 실행합니다.

echo "$USER ALL=(root) NOPASSWD: $CONDA_PREFIX/bin/pinkrab-footswitch" | sudo tee /etc/sudoers.d/pinkrab-footswitch
sudo chmod 440 /etc/sudoers.d/pinkrab-footswitch
sudo visudo -c

페달은 root 로 실행하는 것만으로는 부족하고, studio 를 실행한 앱에 입력 모니터링 권한도 있어야 macOS 가 페달 입력을 읽게 해 줍니다. 시스템 설정 → 개인정보 보호 및 보안 → 입력 모니터링에서 사용하는 터미널 앱을 켜고 터미널을 다시 시작합니다.

Ubuntu

서보 보드는 시리얼 포트로 잡히는데, 시리얼 포트는 dialout 그룹에 속한 사용자만 열 수 있습니다. 풋 페달은 udev rule 을 넣어야 일반 사용자도 열 수 있습니다. 그룹에 추가한 뒤에는 로그아웃했다가 다시 로그인해야 하고, rule 을 넣은 뒤에는 페달을 뽑았다가 다시 꽂아야 적용됩니다.

sudo usermod -aG dialout "$USER"
sudo cp scripts/udev/60-pinkrab.rules /etc/udev/rules.d/
sudo udevadm control --reload && sudo udevadm trigger

SAM 3 환경

dataset 을 만들 때 그리퍼 영상의 배경을 무작위로 바꾸려면, 영상에서 작업 물체를 찾는 SAM 3 가 있어야 합니다. 배경을 바꾸지 않을 거라면 이 단계는 건너뜁니다. SAM 3 는 LeRobot 이 허용하는 것보다 새로운 torch 를 쓰기 때문에, Pinkrab 환경과 따로 ~/pinkrab/sam3-env 에 설치합니다. 설치하는 SAM 3 는 macOS(MPS)와 CUDA 에서 함께 돌도록 고친 sam3-silicon-mac 입니다.

uv venv --python 3.12 ~/pinkrab/sam3-env
uv pip install --python ~/pinkrab/sam3-env/bin/python "torch>=2.15" torchvision \
  "sam3[video] @ git+https://github.com/woolimi/sam3-silicon-mac.git"

SAM 3 의 가중치는 Hugging Face 에서 승인을 받아야 받을 수 있습니다. facebook/sam3 에서 접근을 요청해 승인되면 한 번 로그인합니다. 가중치는 처음 쓸 때 내려받습니다.

~/pinkrab/sam3-env/bin/hf auth login

GPU 가 있는 다른 컴퓨터에서 SAM 3 를 돌릴 거라면 이 컴퓨터에는 설치하지 않아도 됩니다. 그 컴퓨터에는 studio 가 같은 환경을 만듭니다(SAM 3 를 돌릴 컴퓨터).

SAM 3 와 그 가중치는 Meta 의 SAM License 를 따릅니다. Pinkrab 저장소에는 SAM 3 의 코드도 가중치도 들어 있지 않습니다.

설치 확인

pinkrab doctor

pinkrab doctor 는 로봇을 움직이지 않고 환경과 서보 보드, description 을 점검합니다. 빠진 것이 있으면 무엇이 빠졌는지와 함께 고치는 명령을 알려 줍니다.