7. 로봇 개발 환경 세팅하기
하드웨어보다 먼저 무너지는 것
로봇 초보자는 모터나 센서를 먼저 걱정하지만, 실제로 프로젝트를 멈추게 하는 건 개발 환경이다. 어제 되던 코드가 오늘 안 되고, 보드는 잡혔는데 업로드가 안 되고, 라즈베리파이에서는 되는데 Jetson에서는 패키지가 꼬이는 식이다. 환경 세팅은 멋진 부품이 아니라 눈에 잘 띄지 않는 바닥 공사다. 바닥이 삐걱거리면 로봇도 함께 삐걱거린다.
이 장의 목표는 딱 하나다. 앞으로 만들 프로젝트에서 코드보다 환경 때문에 지치지 않도록, 개인 개발자 기준의 현실적인 작업대를 먼저 만드는 것이다.
먼저 그림부터: 개발용 PC, 로봇 본체, 마이크로컨트롤러
로봇 개발 환경은 보통 한 대의 컴퓨터로 끝나지 않는다. 노트북 한 대만 있으면 될 것 같지만, 실제로는 역할이 나뉜다.
주 개발기: VS Code, Git, 시뮬레이션, 문서 작성, 모델 다운로드를 맡는 노트북이나 데스크톱
로봇 본체: 라즈베리파이 또는 Jetson처럼 로봇 위에서 실제 코드를 실행하는 보드 컴퓨터
제어기: 아두이노 같은 MCU로 센서 읽기와 모터 제어를 담당하는 작은 보드
이 셋을 한 덩어리로 보지 말고 연결된 팀으로 생각하면 환경 설계가 쉬워진다. 주 개발기에서는 편하게 코드를 짜고, 로봇 본체에서는 리눅스 기반 서비스를 돌리고, MCU에서는 빠르고 단순한 제어를 맡긴다.
운영체제와 폴더 구조부터 정리하자
이 책은 우분투 계열 리눅스를 기준으로 설명한다. 이유는 단순하다. 로봇 도구, 드라이버, 문서, 예제가 가장 풍부하고, ROS 2와 각종 센서 패키지가 대체로 우분투를 중심으로 돌아가기 때문이다. 윈도우나 macOS에서도 개발은 가능하지만, 실제 로봇 본체는 결국 리눅스에 가까워지는 경우가 많다.
처음부터 폴더 구조를 정해 두면 프로젝트가 늘어나도 덜 헷갈린다. 예를 들어 홈 디렉터리 아래에 ~/robotics 폴더를 만들고, 그 안을 projects, venvs, firmware, data 정도로 나누면 충분하다. 파일이 흩어지는 순간부터 디버깅도 함께 흩어진다.
아래 정도는 처음에 한 번 준비해 두면 편하다.
sudo apt update
sudo apt install -y build-essential cmake git curl wget unzip \
python3 python3-pip python3-venv \
openssh-client openssh-server \
tmux htop
mkdir -p ~/robotics/{projects,venvs,firmware,data}여기서 build-essential은 C/C++ 컴파일러 묶음이고, cmake는 프로젝트 빌드 도구, tmux는 원격 접속이 끊겨도 작업을 이어가기 좋은 터미널 멀티플렉서다. 이름은 낯설어도, 나중에 없어서 아쉬워지는 친구들이다.
Python 세팅: 가장 먼저 안정화할 언어
개인 로봇 개발에서 Python은 만능 조수에 가깝다. 카메라 테스트, 시리얼 통신, 빠른 프로토타이핑, API 호출, 간단한 AI 추론까지 대부분 Python으로 시작해도 된다. 다만 편하다고 아무 환경에나 막 설치하면 나중에 반드시 대가를 치른다.
ROS 2 바이너리 환경을 쓸 계획이라면, 시스템 Python과 맞지 않는 별도 인터프리터를 사용하는 방식은 주의해야 한다. 특히 공식 문서도 conda는 ROS 2 바이너리와 인터프리터가 맞지 않아 호환성 문제가 생길 가능성이 높다고 경고한다.1 그래서 초보자에게는 conda보다 시스템 Python 위에 venv를 얹는 방식을 권한다.
python3 -m venv ~/robotics/venvs/robot
source ~/robotics/venvs/robot/bin/activate
python -m pip install --upgrade pip wheel이제 이 가상환경 안에 필요한 패키지를 넣는다.
pip install numpy pyserial opencv-python중요한 습관은 두 가지다. 하나는 프로젝트마다 가상환경을 나누는 것, 다른 하나는 requirements.txt 같은 파일로 의존성을 기록하는 것이다.
pip freeze > requirements.txt작은 로봇 프로젝트는 처음엔 장난감처럼 가볍다. 그런데 카메라 패키지 하나, 음성 패키지 하나, AI 패키지 하나가 들어오면 금방 무거워진다. 환경을 분리하지 않으면, 컵라면에 케이블 타이와 나사를 같이 넣어 끓이는 기분을 맛보게 된다.
C++ 세팅: 느리게 배우지만 오래 가는 근육
Python이 빠르게 시작하게 해주는 언어라면, C++는 성능과 제어력을 주는 언어다. 로봇에서는 특히 센서 드라이버, 고속 제어 루프, ROS 2의 성능 민감한 노드에서 자주 등장한다. 처음부터 능숙할 필요는 없지만, 빌드와 디버깅 도구는 미리 갖춰 두는 편이 좋다.
sudo apt install -y g++ gdb cmake pkg-config여기서 g++는 C++ 컴파일러, gdb는 디버거다. 디버거는 처음엔 멀게 느껴지지만, 모터가 왜 멈췄는지보다 프로그램이 어디서 멈췄는지를 먼저 잡아주는 도구다. 로봇은 하드웨어 문제처럼 보이는 소프트웨어 문제가 아주 많다.
초보자라면 C++ 공부 자체보다 다음 세 가지를 익히는 것이 더 중요하다.
소스 파일을 컴파일해서 실행 파일을 만드는 흐름
헤더 파일과 구현 파일의 역할 차이
CMakeLists.txt가 빌드를 어떻게 설명하는지 읽는 법
이 세 가지만 알아도 이후 ROS 2 패키지를 읽을 때 덜 무섭다.
Arduino IDE와 Arduino CLI: MCU 작업대 만들기
아두이노는 로봇의 손발 신경을 빠르게 시험해 보기 좋은 도구다. 모터 드라이버 테스트, 초음파 센서 확인, 엔코더 읽기, 서보 제어처럼 하드웨어에 가까운 일은 여전히 강력하다. 공식 Arduino IDE 2 계열은 이전 세대보다 더 현대적인 편집기, 자동완성, 코드 탐색, 라이브 디버거 같은 기능을 제공한다.2
처음에는 Arduino IDE로 시작하는 것이 가장 편하다. 보드를 연결하고 예제 Blink를 올려 보는 데까지 성공하면 절반은 끝난 셈이다. 다만 리눅스에서 자주 막히는 건 보드 인식이 아니라 권한 문제다. 시리얼 포트 권한이 없으면 업로드가 실패한다. 터미널 기반 작업을 하려면 Arduino CLI도 아주 유용하고, 리눅스에서는 dialout 그룹 권한과 보드 식별, FQBN 선택이 핵심 포인트다.3
sudo usermod -a -G dialout $USER이 명령 뒤에는 로그아웃 후 다시 로그인해야 적용되는 경우가 많다. 보드를 꽂았을 때 포트가 무엇인지 확인하려면 다음 명령이 도움이 된다.
arduino-cli config init
arduino-cli core update-index
arduino-cli board list예를 들어 우노 보드라면 이런 식으로 컴파일하고 업로드할 수 있다.
arduino-cli core install arduino:avr
arduino-cli compile --fqbn arduino:avr:uno Blink
arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:avr:uno Blink클론 보드는 /dev/ttyUSB0로 잡히는 경우도 많고, 자동 인식이 안 될 수도 있다. 이때는 당황하지 말고 포트 이름과 FQBN을 직접 지정하면 된다. 로봇 개발자는 결국 부품보다 로그를 더 자주 보게 된다.
VS Code: 가장 무난하고 강력한 기본 편집기
개인 개발자에게 VS Code는 사실상 기본 작업대다. Python, C++, Git, Docker, 원격 접속을 한 화면에서 묶어 주기 때문이다. 특히 로봇 개발에서는 편집기 그 자체보다 확장 기능 구성이 중요하다. 교육 현장에서도 Python, Docker, ROS, Remote Development 계열 확장을 함께 쓰는 구성이 널리 권장된다.4
처음 설치한 뒤에는 확장 기능부터 정리하자.
Python
C/C++
GitLens
Remote - SSH
Docker
Dev Containers
ROS 관련 확장
여기서 핵심은 두 가지다. 첫째, Python 인터프리터를 지금 쓰는 가상환경으로 정확히 맞추는 것. 둘째, 로컬 폴더와 원격 장치 폴더를 헷갈리지 않는 것이다. 같은 파일처럼 보여도 실제 실행 위치가 다르면 증상도 완전히 달라진다.
좀 더 욕심이 생기면 devcontainer도 훌륭한 선택이다. 실제로 ROS 2 개발 환경을 컨테이너와 VS Code 디버깅, 린팅, 테스트까지 묶어서 관리하는 예제들이 이미 공개되어 있다.5 처음부터 꼭 필요하진 않지만, 프로젝트가 둘 이상으로 늘어나는 순간부터 엄청난 시간을 아껴 준다.
Git과 GitHub: 백업이 아니라 실험 기록장
로봇 프로젝트는 코드만 바뀌는 게 아니다. 핀 번호가 바뀌고, 모터 방향이 바뀌고, 카메라 해상도가 바뀌고, 모델 파일이 바뀐다. 그래서 Git은 단순한 백업 도구가 아니라 실험의 역사책에 가깝다.
처음엔 이 정도만 익히면 된다.
cd ~/robotics/projects/my_robot
git init
git add .
git commit -m 'initial setup'원격 저장소를 만들었다면 다음처럼 연결한다.
git branch -M main
git remote add origin <YOUR_GITHUB_REPO_URL>
git push -u origin main여기서 중요한 것은 자주 커밋하는 습관이다. 커밋 메시지는 거창할 필요 없다. camera test ok, fix motor direction, add serial parser처럼 작고 명확하면 된다. 나중에 문제를 되짚어 볼 때 가장 강력한 힌트가 된다.
그리고 .gitignore는 꼭 만들어 두자. 다음 같은 파일은 보통 저장소에 올리지 않는다.
가상환경 폴더
빌드 결과물
대용량 모델 파일
개인 설정 파일
로그 파일
GitHub를 쓰면 협업뿐 아니라, 미래의 나와 협업하기도 쉬워진다. 개인 개발자에게 이 차이는 생각보다 크다.
리눅스 터미널: 이 정도는 손에 익혀 두자
로봇 개발에서 터미널은 선택 과목이 아니다. GUI가 멀쩡해 보여도, 결국 문제를 알려주는 건 터미널인 경우가 많다. 최소한 아래 명령은 자연스럽게 쓸 수 있어야 한다.
pwd,ls,cd: 지금 어디 있는지 확인하고 이동하기mkdir,cp,mv,rm: 파일과 폴더 다루기cat,less,grep,find: 로그와 설정 파일 찾기chmod,sudo: 권한 조정하기ps,top,htop: 어떤 프로세스가 돌고 있는지 보기dmesg,lsusb: USB 장치와 보드 연결 상태 확인하기
예를 들어 아두이노나 USB 센서를 꽂은 뒤 장치 이름이 궁금하면 이렇게 볼 수 있다.
dmesg | tail
ls /dev/ttyACM*
ls /dev/ttyUSB*카메라가 제대로 보이는지 확인하고 싶다면 ls /dev/video*도 유용하다. 로봇 개발 초반에는 멋진 알고리즘보다 이런 작은 확인 명령이 더 큰 문제를 해결해 준다.
원격 접속: 모니터 없는 로봇을 다루는 법
실제 로봇은 책상 위 PC처럼 키보드와 모니터를 항상 붙여 두고 쓰지 않는다. 그래서 원격 접속이 필수다. 가장 기본은 SSH다.
로봇 본체에서 SSH 서버를 켠다.
sudo apt install -y openssh-server
hostname -I이제 개발용 PC에서 접속한다.
ssh <user>@<robot_ip>파일을 복사할 때는 scp를 쓸 수 있다.
scp test.py <user>@<robot_ip>:~/robotics/projects/프로젝트 폴더 전체를 자주 보낼 일이라면 rsync가 더 편하다.
rsync -av ./my_robot/ <user>@<robot_ip>:~/robotics/projects/my_robot/VS Code의 Remote - SSH를 쓰면 체감이 확 좋아진다. 코드는 내 노트북에서 편하게 보는 것 같지만, 실제 파일과 터미널은 로봇 본체에 붙어 있다. 책상 위는 깔끔해지고, 로봇은 한결 덜 성가셔진다.
Docker: 잘 되던 환경을 얼려 두는 냉동고
Docker는 애플리케이션과 실행에 필요한 의존성을 함께 묶어 배포하는 컨테이너 도구다. 호스트 환경과 어느 정도 분리되기 때문에 설치와 배포를 반복 가능하게 만들고, 특히 Jetson 같은 장치에서는 GPU를 유지한 채 재현 가능한 워크플로를 만드는 데 도움이 된다.6
처음엔 어렵게 느껴지지만, 핵심은 단순하다. 내 컴퓨터 전체를 복제하는 게 아니라, 내 프로그램이 돌아갈 작은 상자를 만드는 것이다. 그 상자 안에는 Python 버전, 라이브러리, 시스템 패키지가 같이 들어간다. 그래서 어제 되던 코드가 오늘 패키지 충돌로 죽는 일을 줄일 수 있다.
가장 먼저 해볼 명령은 이 정도면 충분하다.
docker pull ubuntu:24.04
docker run --rm -it ubuntu:24.04 bash이제 컨테이너 안에서 exit를 치면 사라진다. 가볍고, 실험하기 좋다.
Jetson 계열 장치에서는 GPU를 쓰기 위해 Docker와 NVIDIA Container Toolkit 설정이 중요하다. NVIDIA 문서도 Docker 설치 뒤 런타임 구성과 docker 그룹 권한 설정을 안내하고 있다.7
sudo usermod -aG docker $USER
newgrp dockerJetson에서 AI 로봇 개발을 빨리 시작하고 싶다면, PyTorch나 Transformers, ROS 2 조합을 미리 담아 둔 커뮤니티 컨테이너도 좋은 출발점이 된다.8 다만 초보자라면 첫 단계에서는 직접 만든 간단한 컨테이너 하나부터 이해하는 편이 훨씬 덜 헷갈린다.
개인 개발자를 위한 추천 세팅 3단계
처음부터 모든 도구를 한꺼번에 깔면 오히려 망하기 쉽다. 다음 순서로 넓혀 가는 편이 안전하다.
1단계는 기본 세트다. 우분투, Python 가상환경, VS Code, Git, Arduino IDE만 먼저 잡는다. 이 상태면 센서 테스트와 간단한 MCU 제어까지 충분하다.
2단계는 로봇 세트다. SSH, 시리얼 통신, OpenCV, 원격 편집을 추가한다. 여기까지 오면 라즈베리파이나 Jetson에서 카메라와 이동 로봇을 다루기 시작할 수 있다.
3단계는 확장 세트다. Docker, ROS 2, devcontainer, 시뮬레이션 도구를 붙인다. 이 단계부터는 작은 프로젝트를 반복 재현하고, 나중에 팀 프로젝트로 확장하기도 쉬워진다.
핵심은 욕심을 늦추는 것이다. 도구를 많이 아는 것보다, 지금 쓰는 도구를 흔들림 없이 쓰는 것이 더 중요하다.
자주 막히는 문제와 가장 빠른 해결법
개발 환경에서 반복해서 등장하는 문제는 생각보다 비슷하다.
python은 되는데 원하는 패키지가 없다면, 대개 다른 가상환경을 보고 있다. 먼저which python과python -V를 확인한다.아두이노 업로드가 안 된다면, 포트 이름보다 권한 문제를 먼저 의심한다.
dialout그룹, 케이블 불량, 포트 점유를 차례로 본다.VS Code에서 실행하면 되는데 터미널에서는 안 된다면, 인터프리터와 작업 디렉터리가 다를 가능성이 크다.
원격 로봇에서 모듈이 없다고 나오면, 내 노트북에만 설치했고 로봇 본체에는 설치하지 않은 경우가 많다.
Docker가
permission denied를 뿜으면, 아직docker그룹 권한이 적용되지 않았을 수 있다.ROS 2 명령이 안 잡히면, 대개
setup.bash를 source하지 않았거나 현재 셸이 다른 환경을 보고 있다.
환경 문제는 대부분 거대한 버그가 아니라 작은 불일치에서 시작된다. 그래서 디버깅도 거창하게 하지 말고, 파이썬 버전, 포트 이름, 현재 경로, 사용자 권한, 실행 위치를 하나씩 맞춰 보는 습관이 중요하다.
이 장을 마치기 전에 꼭 끝내 둘 것
다음 장으로 넘어가기 전에, 아래 다섯 가지가 실제로 되는지 확인하자.
VS Code에서 Python 파일을 열고 실행할 수 있다.
Git 저장소를 만들고 첫 커밋을 남길 수 있다.
아두이노 보드를 연결해 예제 스케치를 업로드할 수 있다.
SSH로 로봇 본체에 접속할 수 있다.
Docker 컨테이너를 한 번 실행해 볼 수 있다.
이 다섯 가지만 안정적으로 되면, 이후 프로젝트 장에서 막히는 지점이 확 줄어든다. 로봇 개발은 부품을 사는 일보다, 반복 가능한 작업 환경을 만드는 일에서 실력이 갈린다. 이제 작업대는 준비됐다. 다음 장에서는 이 환경 위에서 실제로 굴러가는 작은 이동 로봇을 만들어 보자.
참고
3Arduino CLI로 리눅스 터미널에서 아두이노 개발하기
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.