Raspberry Pi 5 개발 환경 구축

대상: Raspberry Pi 5로 C++/Python/ROS 등 개발을 하려는 사람, GUI 없이도 PC에서 편하게 개발하고 싶은 사람
환경: Raspberry Pi 5, Raspberry Pi OS (64-bit 기준), 호스트 PC는 Ubuntu 22.04 / Windows 10/11, VS Code 설치됨

1. 문제/주제 요약

Raspberry Pi 5를 개발용 보드로 쓰려면 보통 이렇게 준비하게 됩니다.

  1. MicroSD 카드에 OS(Raspberry Pi OS) 설치
  2. 초기 설정 (로케일, Wi-Fi, SSH, 업데이트 등)
  3. PC에서 VS Code로 SSH 원격 접속해서 개발 (터미널/파일/디버깅까지)

이 글은 **“라즈베리파이 5 박스 개봉 → OS 설치 → VS Code Remote 연결”**까지 한 번에 끝내는 튜토리얼입니다.
GUI 모니터/키보드 없이 처음부터 headless(무모니터)로 세팅하는 흐름 위주로 설명합니다.

2. 배경/개념 간단 정리

2-1. 왜 VS Code 원격 개발?

Raspberry Pi 5는 성능이 좋아졌지만, 그래도 데스크탑 PC보다는 느립니다.

  • 코드 편집/검색/리팩토링/확장 기능 → PC에서 VS Code가 훨씬 쾌적
  • 실제 실행/테스트/센서 연동 → Raspberry Pi 5에서 직접 실행

그래서 보통 아래 구조를 많이 씁니다.

  • 호스트 PC: VS Code + Remote – SSH 플러그인
  • Raspberry Pi 5: SSH 서버, 빌드 도구, 런타임 설치

VS Code가 SSH로 접속해서, Pi의 파일 시스템을 바로 열고, 터미널도 Pi에서 실행한 것처럼 사용할 수 있습니다.

2-2. Headless 세팅의 장점

  • 모니터/키보드/마우스 없이도 전원 + LAN/Wi-Fi만 있으면 세팅 가능
  • 실제 로봇/임베디드 환경처럼 작은 기기 + 네트워크만 연결된 형태를 미리 익힐 수 있음

3. 단계별 설정: OS 설치 → 네트워크 → SSH → VS Code

3-1. Raspberry Pi OS 이미지 준비

1) Raspberry Pi Imager 설치

  • Raspberry Pi 공식 사이트에서 Raspberry Pi Imager를 다운로드하여 설치합니다.
    • Ubuntu: sudo snap install rpi-imager 또는 .deb 다운로드 후 설치
    • Windows/macOS: 설치 파일 받아서 설치

2) Imager 실행 후 설정

  1. Operating System 선택
    • Raspberry Pi OS (64-bit) 선택 (일반 개발 용도로 추천)
  2. Storage에서 사용 중인 MicroSD 카드 선택
  3. 우측 아래 톱니바퀴(설정) 버튼 클릭 → Headless 설정
    • Set hostname: raspberrypi5.local 처럼 알아보기 쉬운 이름으로 설정
    • Enable SSH 체크
      • Use password authentication 선택
      • Username / Password 지정 (기본 pi / raspberry 말고, 본인 계정 추천)
    • Configure wireless LAN (Wi-Fi 사용 시)
      • SSID, Password, Country 설정
    • Locale settings
      • Time zone: Asia/Seoul
      • Keyboard: 예) Generic 105-key (Intl) PC / Korean or English (US)
  4. WRITE 버튼을 눌러 SD 카드에 OS 굽기
  5. 완료되면 SD 카드를 안전하게 제거 후 Raspberry Pi 5에 꽂습니다.

3-2. Raspberry Pi 5 최초 부팅

  1. MicroSD + 전원 + (가능하면) 유선 LAN 연결
  2. 전원을 연결하면 자동 부팅
  3. PC에서 같은 네트워크에 연결된 상태에서 Pi를 찾습니다.

IP 또는 호스트 이름 확인

  • 같은 네트워크에 있다면, 아래 중 하나로 접속 시도:
ping raspberrypi5.local

또는 라우터 관리자 페이지에서 접속된 장치 목록에서 IP 확인 후:

ping 192.168.x.x

핑이 잘 되면 SSH로 접속을 시도합니다.

3-3. SSH 접속 테스트 (터미널에서 먼저)

호스트 PC가 Ubuntu 기준이라면:

ssh <username>@raspberrypi5.local
# 또는
ssh <username>@192.168.x.x

처음 접속 시 fingerprint 경고가 나오면 yes 입력 후, 비밀번호 입력.

접속에 성공했다면 아래처럼 기본 시스템 업데이트부터 해줍니다.

sudo apt update
sudo apt full-upgrade -y
sudo reboot

재부팅 후 다시 SSH 접속이 되는지 확인합니다.

3-4. 개발 도구 기본 설치 (빌드 환경/필수 패키지)

개발용으로 최소한 아래 정도는 깔아두면 편합니다.

sudo apt update
sudo apt install -y \
    build-essential \
    cmake \
    git \
    python3 python3-pip python3-venv \
    pkg-config \
    libopencv-dev # 필요할 때

추가로 ROS/ROS 2, OpenCV, 기타 라이브러리는 프로젝트에 맞게 나중에 설치하면 됩니다.

3-5. VS Code에 Remote – SSH 확장 설치

호스트 PC(노트북/데스크탑)에서:

  1. VS Code 실행
  2. Extensions 탭에서 Remote - SSH 검색 후 설치
    • (요즘은 Remote Development 확장팩 안에 포함되어 있음)

설치가 끝나면 좌측 Activity Bar에 REMOTE EXPLORER 아이콘 또는 아래쪽 왼쪽에 >< 모양 아이콘(원격 표시)이 보입니다.

3-6. VS Code에서 Raspberry Pi 5 SSH 설정

VS Code 명령 팔레트( Ctrl + Shift + P ) 열고:

  1. Remote-SSH: Add New SSH Host... 선택
  2. 아래와 같이 입력:
ssh <username>@raspberrypi5.local
# 또는
ssh <username>@192.168.x.x
  1. 어떤 SSH config 파일에 저장할지 묻는다면 기본 (~/.ssh/config) 선택

이제 ~/.ssh/config에 Raspberry Pi 설정이 추가됩니다.

예시:

Host rpi5
    HostName raspberrypi5.local
    User <username>

이렇게 별칭을 달아두면 VS Code에서 rpi5라고만 써도 됩니다.

3-7. VS Code에서 실제 원격 접속

  1. 다시 명령 팔레트 (Ctrl + Shift + P) →
    Remote-SSH: Connect to Host... 선택
  2. 목록에서 ssh rpi5 또는 ssh <username>@raspberrypi5.local 선택
  3. 우측 하단에 “리모트에 연결 중” 상태가 나오고,
    상단에 SSH: rpi5 같은 표시가 생기면 이제 VS Code 자체가 Raspberry Pi 5에 붙은 상태입니다.

처음 접속 시에는:

  • Pi 쪽에 VS Code 서버 컴포넌트를 설치하는 과정이 뜹니다.
  • 몇 분 걸릴 수 있지만, 한 번 설치해두면 이후부터는 빠르게 붙습니다.

연결 후:

  1. File → Open Folder 선택
  2. /home/<username>/workspace 같은 디렉토리를 새로 만들거나 열기
  3. 이 폴더 안에서 파일 생성, 터미널 열기 등을 하면 모두 Raspberry Pi 5에서 동작합니다.

3-8. VS Code에서 터미널/디버깅/확장 기능 사용

1) 터미널

VS Code에서 Ctrl + Backtick (`Ctrl + “)으로 터미널을 열면,
쉘 프롬프트가 다음처럼 보일 겁니다.

<username>@raspberrypi5:~/workspace $

→ 일반 터미널처럼 git, cmake, python3, colcon 등을 실행하면 됩니다.

2) C++ 빌드/디버깅

  • C/C++ 확장 (ms-vscode.cpptools) 설치
  • CMake Tools, CMake 확장 설치하면 CMake 기반 프로젝트 빌드/디버깅이 편해집니다.

launch.json, tasks.json을 설정하면, Pi 위에서 실행되는 프로그램을 VS Code에서 바로 디버깅할 수 있습니다.

3) Python 개발

  • Python 확장 설치
  • 인터프리터 선택에서 Raspberry Pi의 /usr/bin/python3 선택
  • venv 만들어서 프로젝트별 패키지 관리도 가능합니다.

4. 추가 팁 / 자주 하는 실수

4-1. SSH 안 붙을 때 체크리스트

  1. Pi 전원이 켜져 있는지 / 부팅이 되었는지
  2. 같은 네트워크 대역인지 (예: 192.168.0.x vs 192.168.1.x)
  3. ping raspberrypi5.local 또는 ping <IP> 가 되는지
  4. ssh <username>@IP -v 로 디버그 로그를 보면서 어디서 막히는지 확인

만약 아예 응답이 없다면,

  • Wi-Fi SSID/비밀번호를 잘못 입력했을 가능성이 큼 → SD 카드 다시 굽거나,
  • 유선 LAN을 꽂고 라우터에서 IP 확인하는 것도 방법입니다.

4-2. 비밀번호 로그인 vs SSH 키 로그인

처음에는 비밀번호 기반으로 접속해도 되지만, 자주 사용할 경우 SSH 키 기반 로그인이 훨씬 편하고 안전합니다.

호스트 PC에서:

ssh-keygen -t ed25519 -C "rpi5-dev"
ssh-copy-id <username>@raspberrypi5.local

이후에는 비밀번호 없이 접속 가능 (처음 한 번 키 passphrase 입력할 수 있음).

4-3. locale / 시간대 꼬였을 때

  • 로그 시간, ROS 메시지 타임스탬프 등을 맞추려면 시간대/시간 동기화가 중요합니다.

Pi에서:

sudo raspi-config
# Localisation Options -> Timezone -> Asia -> Seoul

또는 Raspberry Pi OS GUI가 있다면 설정에서 Time Zone 변경.

4-4. 성능 이슈 (VS Code 느릴 때)

  • MicroSD 카드 속도가 느리면 전체 작업이 답답해질 수 있습니다.
    • 가능하면 A2 등급, U3 이상 SD 카드 사용 추천
  • 대규모 빌드(예: ROS 2 전체 빌드)는 Pi가 뜨거워지고 느릴 수 있으니,
    • 히트싱크/쿨링, 혹은 크로스 컴파일도 고려할 수 있습니다.

5. 정리

  • Raspberry Pi Imager로 **Raspberry Pi OS(64-bit)**를 SD 카드에 굽고,
    그 과정에서 hostname, Wi-Fi, SSH, locale까지 한 번에 설정하면 headless 세팅이 매우 편해집니다.
  • 부팅 후 SSH로 접속해 **업데이트 + 개발 도구(빌드툴, Python, git 등)**를 설치합니다.
  • VS Code에서 Remote – SSH 확장을 이용하면,
    PC에서 편하게 코드를 편집하면서 실행/빌드는 Raspberry Pi 5에서 수행하는 구조를 만들 수 있습니다.
  • SSH 연결, 네트워크, 권한, locale 등의 기본을 잘 잡아두면
    이후 ROS/ROS2, OpenCV, 하드웨어 제어 코드까지 확장해도 안정적으로 개발 환경을 유지할 수 있습니다.

댓글 남기기