개발환경 구축 — 재현 가능한 ROS 2 개발 기반 만들기

1. 왜 Ubuntu인가, 그리고 대안은

ROS 2는 이론상 여러 운영체제를 지원합니다. 그런데 실무에서는 사실상 Ubuntu입니다. 이유는 기술적인 것이 아니라 현실적인 것입니다.

① 공식 바이너리가 Ubuntu용으로 먼저, 가장 완전하게 나옵니다. 다른 운영체제에서는 직접 빌드해야 하는 패키지가 늘어납니다.

② 남의 패키지가 Ubuntu를 가정하고 만들어집니다. Nav2, MoveIt 2, 각종 드라이버의 설치 안내가 전부 apt 기준입니다. 문제가 생겼을 때 검색해서 나오는 해결책도 마찬가지입니다.

③ 로봇에 실제로 올라가는 것이 Ubuntu입니다. Jetson도, 대부분의 산업용 컨트롤러도 Ubuntu 계열입니다. 개발 환경과 배포 환경이 같으면 "내 컴퓨터에서는 됐는데"가 크게 줄어듭니다.

그래서 선택지는 사실 이렇습니다.

네이티브 Ubuntu (권장) — 성능과 하드웨어 접근이 가장 좋습니다. USB 센서, 실시간성, GPU 모두 문제없습니다. 듀얼 부팅이 번거롭다는 것이 유일한 단점입니다.

Docker — 가장 실용적인 두 번째 선택입니다. 배포판을 여러 개 동시에 쓸 수 있고, 환경이 꼬여도 컨테이너만 지우면 됩니다. 팀 전체가 같은 환경을 쓰게 만들기도 쉽습니다. GUI(RViz2, Gazebo)와 USB 장치는 추가 설정이 필요합니다.

WSL2 (Windows) — 입문과 학습에는 충분히 좋습니다. 다만 USB 직결 하드웨어와 실시간성에서 제약이 있고, 네트워크가 한 겹 더 있어 다른 컴퓨터의 ROS 2 노드와 통신할 때 설정이 까다롭습니다. 실제 로봇을 붙일 계획이라면 결국 Ubuntu로 옮기게 됩니다.

가상머신 — 가장 느립니다. 3D 시뮬레이션은 사실상 포기해야 합니다. 다른 방법이 없을 때의 최후 선택입니다.

결론: 배우는 단계라면 Docker나 WSL2로 시작해도 좋습니다. 하지만 실제 로봇을 만질 계획이라면 네이티브 Ubuntu를 준비하세요.

개념도 · compare

• 단계/참여자
• 배우는 단계
• 실제 로봇을 만드는 단계
• 연결/행
• Docker나 WSL2로 충분하다|네이티브 Ubuntu를 권한다
• 환경이 꼬여도 지우면 된다|USB와 실시간성이 중요해진다
• 시뮬레이션 위주|하드웨어 직결이 늘어난다
• 설치 시간을 아낀다|배포 환경과 같게 맞춘다

지금 무엇을 하려는지에 따라 답이 달라집니다. 실기를 붙일 계획이 기준입니다.

2. 배포판 고르기 — LTS와 EOL

ROS 2는 매년 새 배포판을 냅니다. 그리고 배포판마다 지원하는 Ubuntu 버전이 정해져 있습니다. 이 짝을 어기면 설치 자체가 되지 않습니다.

여기서 중요한 원칙 세 가지

① LTS 배포판을 고르세요. 일반 배포판은 지원 기간이 짧고, LTS는 훨씬 깁니다. 한창 개발 중에 EOL(지원 종료)이 오면 보안 갱신도, 새 패키지 빌드도 멈춥니다.

② 남들이 쓰는 것을 고르세요. 가장 최신 배포판은 아직 지원하지 않는 서드파티 패키지가 많습니다. "Nav2는 되는데 내가 쓰려던 센서 드라이버가 아직 안 나왔다" 같은 일이 흔합니다. 한 세대 뒤가 대개 가장 편합니다.

③ 배포판과 Ubuntu 버전은 반드시 짝을 맞추세요. "Ubuntu 24.04에 옛 배포판을 깔면 안 되나요?"의 답은 "공식적으로는 안 되고, 억지로 하면 계속 문제가 생깁니다"입니다.

정확한 짝과 EOL 날짜는 반드시 공식 문서에서 확인하세요. 이 조합은 시간에 따라 바뀌므로 어떤 교재도 최신 정보를 보장할 수 없습니다. docs.ros.org의 Releases 페이지가 유일하게 믿을 수 있는 출처입니다.

팀 프로젝트라면: 배포판을 팀 전체가 통일하세요. 서로 다른 배포판에서 만든 워크스페이스는 호환되지 않습니다. 이것을 문서 첫 줄에 적어 두는 것만으로 많은 사고를 막을 수 있습니다.

요점

• ROS 2 배포판마다 지원하는 Ubuntu 버전이 정해져 있으며 어기면 설치가 되지 않는다.
• LTS를 고르되, 가장 최신보다 한 세대 뒤가 서드파티 지원 면에서 대개 편하다.
• 정확한 짝과 EOL 날짜는 docs.ros.org에서 직접 확인한다. 교재의 숫자를 믿지 않는다.
• 팀 프로젝트는 배포판을 통일하고 그 사실을 문서 첫 줄에 적는다.
• EOL이 지난 배포판은 보안 갱신과 새 패키지 빌드가 멈춘다.

주의 이 화면은 특정 배포판 이름이나 날짜를 적지 않습니다. 그 정보는 시간이 지나면 반드시 틀리기 때문입니다. 설치 직전에 docs.ros.org의 해당 배포판 Installation 페이지를 열어 두고 따라가세요. 아래 명령들은 "무엇을 왜 하는지"를 보여 주기 위한 뼈대이며, 정확한 문자열은 공식 문서를 따릅니다.

3. 설치 절차 — 각 단계가 무엇을 하는가

설치 안내를 그대로 복사해 붙이면 대개 잘 됩니다. 그런데 각 줄이 무엇을 하는지 알아야 실패했을 때 어디를 고칠지 압니다.

① 로케일(locale) 설정 — UTF-8을 쓰게 만듭니다. 이것을 빠뜨리면 나중에 한글이 섞인 로그나 파일 이름에서 이상한 오류가 납니다. 한국어 환경에서는 특히 빠뜨리지 마세요.

② apt 저장소 등록 — 어디서 ROS 2 패키지를 받아올지 알려 줍니다. 서명 키와 저장소 주소를 등록하는 단계입니다. 이 단계의 명령이 배포판마다 가장 많이 바뀝니다. 반드시 공식 문서를 그대로 따르세요.

③ apt install ros-<배포판>-desktop — 본체를 설치합니다. -desktop은 RViz2와 데모까지 포함한 큰 묶음입니다. 로봇에 올릴 때는 GUI가 필요 없으므로 -ros-base를 씁니다. 용량이 크게 줄어듭니다.

④ 개발 도구 설치 — ros-dev-tools, python3-colcon-common-extensions. 본체만 깔면 빌드를 못 합니다. colcon이 없기 때문입니다. "설치했는데 colcon 명령이 없다"는 여기를 빠뜨린 것입니다.

⑤ rosdep init / rosdep update — 의존성 데이터베이스를 만듭니다. 앞 화면에서 배운 rosdep install이 동작하려면 이것을 먼저 해야 합니다. init은 한 번만, update는 가끔 다시 합니다.

⑥ source /opt/ros/<배포판>/setup.bash — 환경을 켭니다. 이것이 없으면 ros2 명령 자체가 없습니다. 앞 화면에서 배운 underlay가 바로 이것입니다.

설치 6단계의 뼈대. 정확한 문자열은 공식 문서를 따르되, 각 단계가 무엇을 하는지 알고 진행하세요.

# ============================================================
# 설치 절차의 "뼈대"
# 정확한 명령은 배포판마다 다릅니다.
# 반드시 docs.ros.org 의 해당 배포판 Installation 페이지를 따르세요.
# ============================================================

# ── ① 로케일을 UTF-8 로 ─────────────────────────────────
locale                                  # 지금 상태 확인
sudo apt update && sudo apt install -y locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8


# ── ② apt 저장소 등록 ───────────────────────────────────
# 이 단계의 명령이 배포판마다 가장 많이 바뀝니다.
# 서명 키를 받아 등록하고 ROS 2 저장소 주소를 apt 에 알려 주는 단계입니다.
# (공식 문서의 Setup Sources 절을 그대로 따르세요)
sudo apt install -y software-properties-common curl
sudo add-apt-repository universe


# ── ③ 본체 설치 ─────────────────────────────────────────
sudo apt update
sudo apt upgrade -y

# 개발용 PC: RViz2 와 데모까지 포함
sudo apt install -y ros-<배포판>-desktop

# 로봇에 올릴 때: GUI 없이. 용량이 크게 줄어든다.
# sudo apt install -y ros-<배포판>-ros-base


# ── ④ 개발 도구 (본체만으로는 빌드할 수 없다) ────────────
sudo apt install -y ros-dev-tools
sudo apt install -y python3-colcon-common-extensions
# colcon 명령이 없다면 이 줄을 빠뜨린 것이다.


# ── ⑤ 의존성 데이터베이스 ───────────────────────────────
sudo rosdep init          # 한 번만. 이미 했다면 오류가 나는데 정상이다.
rosdep update             # 사용자 계정으로. sudo 없이.


# ── ⑥ 환경 켜기 ─────────────────────────────────────────
source /opt/ros/<배포판>/setup.bash

# 매번 치기 번거로우니 .bashrc 에 넣는다 (underlay 만!)
echo "source /opt/ros/<배포판>/setup.bash" >> ~/.bashrc

주의 sudo rosdep init은 이미 실행한 적이 있으면 "already exists" 오류를 냅니다. 이것은 정상이며 무시해도 됩니다. 반대로 rosdep update는 sudo 없이 사용자 계정으로 실행해야 합니다. sudo로 실행하면 캐시가 root 소유가 되어 나중에 권한 오류가 납니다.

4. 설치 직후 반드시 확인할 네 가지

설치가 끝났다고 넘어가면 안 됩니다. 아래 네 가지를 순서대로 확인하세요. 여기서 걸러 내지 않으면 나중에 훨씬 찾기 어려운 문제가 됩니다.

① ros2 명령이 있는가 ros2 --help가 나오지 않으면 source를 안 한 것입니다.

② 통신이 되는가 — talker와 listener 터미널 두 개를 열어 데모 노드를 띄웁니다. 이것이 되면 미들웨어, 디스커버리, 직렬화가 모두 정상이라는 뜻입니다. 가장 값어치 있는 한 번의 확인입니다.

③ 빌드가 되는가 — 빈 워크스페이스 빌드 colcon build가 오류 없이 끝나야 합니다. 여기서 실패하면 개발 도구 설치를 빠뜨린 것입니다.

④ GUI가 뜨는가 — RViz2 Docker나 WSL2, 가상머신에서는 여기서 막히는 경우가 많습니다. ros2 run rviz2 rviz2가 창을 띄우면 GUI 설정이 끝난 것입니다.

그리고 ros2 doctor 이 명령은 환경을 스스로 점검해 문제를 보고합니다. ros2 doctor --report는 더 자세한 정보를 냅니다. 남에게 도움을 요청할 때 이 출력을 함께 보내면 대화가 훨씬 빨라집니다.

두 대 이상을 쓴다면 여기서 한 가지 더: 서로 다른 컴퓨터의 노드가 보이는지 확인하세요. 같은 ROS_DOMAIN_ID, 같은 네트워크, 방화벽 해제가 필요합니다. ros2 multicast send와 ros2 multicast receive로 ROS 2 이전 단계에서 네트워크 자체가 되는지를 먼저 가릴 수 있습니다.

설치 확인 4단계와 네트워크 진단. ②의 talker/listener가 가장 값어치 있는 확인입니다.

# ── ① ros2 명령이 있는가 ────────────────────────────────
ros2 --help
printenv | grep -i ros
# ROS_DISTRO, ROS_VERSION, AMENT_PREFIX_PATH 가 보여야 한다


# ── ② 통신이 되는가 (가장 중요한 확인) ───────────────────
# 터미널 1
ros2 run demo_nodes_cpp talker

# 터미널 2 (반드시 새로 열고 source 한 뒤)
ros2 run demo_nodes_py listener
# "I heard: [Hello World: 1]" 이 나오면
# 미들웨어, 디스커버리, 직렬화가 모두 정상이라는 뜻이다.

# 터미널 3 — 밖에서도 보이는지
ros2 topic list
ros2 topic echo /chatter --once


# ── ③ 빌드가 되는가 ─────────────────────────────────────
mkdir -p ~/ros2_ws/src && cd ~/ros2_ws
colcon build
# "colcon: command not found" 라면 개발 도구 설치를 빠뜨린 것이다.
source install/setup.bash


# ── ④ GUI 가 뜨는가 ─────────────────────────────────────
ros2 run rviz2 rviz2
# Docker, WSL2, 가상머신에서는 여기서 막히는 경우가 많다.


# ── 환경 자체를 점검하기 ────────────────────────────────
ros2 doctor
ros2 doctor --report        # 도움을 요청할 때 이 출력을 함께 보낸다


# ── 두 대 이상을 쓸 때 ──────────────────────────────────
# ROS 2 이전에 네트워크 자체가 되는지 먼저 가린다
# 컴퓨터 A
ros2 multicast receive
# 컴퓨터 B
ros2 multicast send
# 여기서 안 되면 ROS 문제가 아니라 네트워크나 방화벽 문제다.

# 방화벽 확인 (필요하면 해제)
sudo ufw status

개념도 · flow

• 단계/참여자
• ros2 --help — source 되었는가
• talker와 listener — 통신이 되는가
• colcon build — 개발 도구가 있는가
• rviz2 — GUI가 되는가
• ros2 doctor — 남은 문제는 없는가
• 연결/행
• 안 되면 source
• 안 되면 미들웨어
• 안 되면 도구 누락
• 안 되면 GUI 설정
• ``

앞 단계가 되어야 뒤 단계가 의미 있습니다. 실패한 지점이 원인을 알려 줍니다.

5. 환경변수 — 알아야 할 네 가지

설치가 끝나면 환경변수 몇 개를 이해해야 합니다. 이것들이 다른 사람과 섞이지 않게 해 주는 장치입니다.

① ROS_DOMAIN_ID — 가장 중요합니다. 같은 Discovery 범위에서 같은 값을 사용하는 Node가 같은 DDS Domain에 참여합니다. 기본값 0을 공유하면 강의실에서 옆 사람의 로봇이 내 명령을 받을 수 있습니다. Domain ID의 유효 범위와 OS별 안전 권장 범위는 DDS Port 및 Ephemeral Port 범위에 영향을 받으므로 ROS 2 공식 Domain ID 안내를 확인하고 조직에서 충돌하지 않는 값을 배정합니다.

② Discovery 범위 설정 — 내 Computer 또는 Subnet으로 발견 범위를 제한합니다. 기존 배포판은 ROS_LOCALHOST_ONLY를 사용했고 최신 배포판은 ROS_AUTOMATIC_DISCOVERY_RANGE와 ROS_STATIC_PEERS를 제공합니다. 지원 여부와 값은 사용 중인 배포판 문서를 확인합니다. 혼자 실습할 때 Localhost로 제한하면 다른 Robot과 섞이지 않지만 여러 Computer 실험에서는 Subnet 또는 명시적 Peer 구성이 필요합니다.

③ RMW_IMPLEMENTATION — 어떤 DDS 구현을 쓸지 고릅니다. 기본값이 있으므로 보통은 건드리지 않습니다. 다만 통신 문제를 진단할 때 다른 구현으로 바꿔 보면 "내 코드 문제인가 미들웨어 문제인가"를 가를 수 있습니다. 서로 다른 DDS Vendor도 표준 Protocol을 통해 통신하도록 설계됐지만 Discovery 설정, QoS 기능, Security와 배포판 조합에 따라 차이가 생길 수 있습니다. 진단 시험에서는 먼저 모든 Process를 같은 RMW로 맞춰 변수 하나를 제거한 뒤 필요하면 상호운용성을 별도로 검증합니다.

④ ROS_DISTRO — 지금 어떤 배포판이 켜져 있는지 알려 줍니다. 직접 설정하는 것이 아니라 source가 채워 줍니다. 여러 배포판을 오갈 때 확인용으로 씁니다.

.bashrc 관리 요령 underlay(/opt/ros/...)와 ROS_DOMAIN_ID는 넣어도 좋습니다. 하지만 워크스페이스 overlay는 넣지 마세요. 앞 화면에서 말한 대로 어느 것이 켜져 있는지 헷갈리게 됩니다.

여러 배포판을 함께 쓴다면: .bashrc에 아무것도 넣지 말고, 배포판별로 켜는 함수를 만들어 두는 편이 안전합니다.

환경변수 설정과 확인. 도메인 ID를 정해 두는 것만으로 "옆 사람 로봇이 움직이는" 사고를 막습니다.

# ── .bashrc 에 넣기 좋은 것들 ───────────────────────────
# underlay 와 도메인 ID 까지만. overlay 는 넣지 않는다.
source /opt/ros/<배포판>/setup.bash
export ROS_DOMAIN_ID=42          # 예시 값. 조직 정책과 OS 권장 범위를 확인한다.


# ── 혼자 실습할 때 (남과 섞이지 않게) ────────────────────
export ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST

# 두 대 이상으로 실험할 때는 반드시 꺼야 한다
export ROS_AUTOMATIC_DISCOVERY_RANGE=SUBNET


# ── 지금 설정을 확인 ────────────────────────────────────
echo $ROS_DISTRO
echo $ROS_DOMAIN_ID
echo $ROS_LOCALHOST_ONLY
echo $ROS_AUTOMATIC_DISCOVERY_RANGE
echo $RMW_IMPLEMENTATION
printenv | grep -i ros


# ── 통신 문제를 진단할 때 DDS 구현 바꿔 보기 ──────────────
# 진단 비교에서는 모든 관련 Process를 같은 RMW로 맞춰 변수를 줄인다.
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
# 또는
export RMW_IMPLEMENTATION=rmw_fastrtps_cpp

# 설치된 구현 목록 확인
ros2 doctor --report | grep -i rmw


# ── 여러 배포판을 오갈 때: .bashrc 대신 함수 ─────────────
# ~/.bashrc 에 아래를 넣어 두고 필요할 때만 부른다.
#
#   ros_a() { source /opt/ros/<배포판A>/setup.bash; export ROS_DOMAIN_ID=42; }
#   ros_b() { source /opt/ros/<배포판B>/setup.bash; export ROS_DOMAIN_ID=43; }
#
# 한 셸에서 두 배포판을 겹쳐 source 하면 반드시 문제가 생긴다.
# 배포판을 바꿀 때는 새 터미널을 여는 것이 가장 안전하다.

주의 한 셸에서 서로 다른 ROS 2 배포판을 겹쳐 source 하면 반드시 문제가 생깁니다. 경로가 뒤섞여 어느 쪽 라이브러리가 쓰이는지 알 수 없게 되고, 증상은 매우 이상하게 나타납니다. 배포판을 바꿀 때는 반드시 새 터미널을 여세요.

6. 설치가 꼬였을 때

① ros2: command not found → source /opt/ros/<배포판>/setup.bash를 했는가? → 배포판 이름의 철자가 맞는가? → ls /opt/ros/로 실제로 무엇이 설치되어 있는지 확인합니다.

② colcon: command not found → 개발 도구를 설치하지 않았습니다. python3-colcon-common-extensions를 설치하세요.

③ apt가 패키지를 못 찾는다 → 저장소 등록 단계가 실패했거나 apt update를 안 했습니다. → Ubuntu 버전과 배포판의 짝이 맞는지 다시 확인하세요. 짝이 안 맞으면 저장소에 그 패키지가 아예 없습니다.

④ rosdep이 실패한다 → rosdep update를 sudo로 실행한 적이 있다면 Cache 소유권을 확인합니다. 먼저 rosdep fix-permissions가 제공되는지 확인해 권한을 복구하고 이후 rosdep update는 일반 사용자로 실행합니다. Home Directory를 재귀 삭제하는 명령은 사용하지 않습니다.

⑤ talker/listener가 서로를 못 본다 → 두 Terminal의 ROS_DOMAIN_ID와 Discovery 범위가 같은가? → 진단 중이라면 RMW_IMPLEMENTATION을 같은 값으로 맞췄는가? → ros2 daemon stop 후 다시 확인합니다. CLI Daemon Cache가 오래된 경우가 있습니다.

⑥ 다른 컴퓨터의 노드가 안 보인다 → ros2 multicast send/receive로 네트워크 자체를 먼저 확인합니다. → 방화벽, 같은 서브넷 여부, Wi-Fi의 클라이언트 격리 설정을 봅니다. → 회사나 학교 Wi-Fi는 기기 간 통신을 막는 경우가 많습니다.

⑦ Docker에서 GUI가 안 뜬다 → X11 소켓 공유와 DISPLAY 전달이 필요합니다. → GPU를 쓰려면 추가 설정이 더 있습니다.

재설치 전: Package 목록, Apt Source, Key, OS Codename과 오류 Log를 먼저 보존합니다. 전체 ROS Package 제거는 넓은 범위의 변경이므로 대상 Package를 apt list --installed로 확인하고 Backup·복구 계획을 세운 뒤 수행합니다. Docker 환경은 Image를 다시 만들기 쉽지만 Volume, Device, Network와 Host Driver 문제까지 자동으로 해결해 주지는 않습니다.

7. 설치 전에 환경 명세를 먼저 쓴다

설치는 명령 복사가 아니라 지원되는 조합을 선택하고 기록하는 작업입니다. 다음 표를 채운 뒤 설치를 시작하면 팀원이 같은 환경을 다시 만들 수 있습니다.

# OS와 Architecture
uname -m
uname -a
cat /etc/os-release

# CPU·Memory·Disk
lscpu
free -h
df -h

# GPU가 있는 경우
lspci | rg -i 'vga|3d|nvidia|amd|intel'
nvidia-smi  # NVIDIA Driver가 설치된 장비에서만

# 설치 후 ROS 기준
echo "$ROS_DISTRO"
ros2 doctor --report

Project Repository에는 다음처럼 사람이 읽는 환경 문서를 둡니다.

# environment.yaml — 예시 명세이며 자동 설치 Script가 아니다.
os:
  family: ubuntu
  version: "<팀이 검증한 LTS>"
  architecture: amd64
ros:
  distribution: "<팀이 검증한 ROS 2 배포판>"
  variant: desktop
  rmw: rmw_cyclonedds_cpp
workspace:
  build_type: symlink-install
network:
  domain_id: 42
  discovery_range: LOCALHOST
tested_at: "YYYY-MM-DD"

Distribution과 Ubuntu의 정확한 지원표는 시간이 지나면 바뀝니다. 설치 당일 공식 ROS 2 Releases와 해당 Distribution의 Binary Installation 문서를 확인하고, 팀 문서에는 확인 날짜와 Link까지 남깁니다.

8. Native Ubuntu 설치를 안전하게 진행한다

공식 Debian Package 설치의 흐름은 다음과 같습니다.

OS 지원 조합 확인
  → UTF-8 Locale 확인
  → Universe 등 OS Repository 준비
  → 공식 ros2-apt-source 또는 안내된 Source 등록
  → apt update
  → Desktop / ROS Base 설치
  → ros-dev-tools 설치
  → rosdep 초기화·갱신
  → setup.bash Source
  → Demo·Build·GUI 검증

Repository Key와 Source 등록 방식은 보안과 배포 Infrastructure 변화에 따라 바뀔 수 있습니다. 오래된 Blog의 apt-key 명령을 복사하지 말고 해당 Distribution 공식 설치 문서를 사용합니다. 명령 안의 Distribution 이름을 추측해서 섞지 않습니다.

Desktop과 ROS Base 선택

• Desktop: RViz, Demo와 개발 PC에 필요한 도구를 포함합니다.
• ROS Base: GUI가 필요 없는 Robot Computer, CI와 최소 Container에 적합합니다.
• Simulation, Nav2, MoveIt, Camera Driver는 별도 Package가 필요할 수 있습니다.

설치 직후 Package 상태를 기록합니다.

apt-cache policy "ros-${ROS_DISTRO}-desktop"
apt list --installed 2>/dev/null | rg "^ros-${ROS_DISTRO}-" > ros-packages.txt
dpkg --print-architecture

apt upgrade는 System 전체를 바꿀 수 있으므로 Robot Release 직전 무조건 수행하지 않습니다. 개발 Image에서 먼저 Upgrade하고 Test를 통과한 Version을 Robot Fleet에 단계적으로 배포합니다.

9. Shell 환경을 예측 가능하게 관리한다

ROS Environment는 Underlay와 Overlay를 순서대로 Source해 구성됩니다.

/opt/ros/<distro>/setup.bash       ← ROS Underlay
~/robot_ws/install/setup.bash      ← Project Overlay
~/experiment_ws/install/setup.bash ← 추가 Overlay

뒤에 Source한 Overlay가 앞 환경의 Package를 덮어쓸 수 있습니다. 여러 Workspace를 .bashrc에 자동 Source하면 현재 Shell이 어떤 Package를 사용하는지 알기 어려워집니다.

# 깨끗한 Shell에서 시작
bash --noprofile --norc

# Underlay만 적용
source "/opt/ros/<배포판>/setup.bash"

# 필요한 Project만 적용
source "$HOME/robot_ws/install/setup.bash"

# 실제 Package 경로 확인
ros2 pkg prefix my_robot_bringup
python3 -c 'import sys; print("\n".join(sys.path))'

팀에서는 자동 Source 대신 명시적인 함수나 Script를 사용할 수 있습니다.

# ~/.bashrc 예시
use_robot_ws() {
  source /opt/ros/<배포판>/setup.bash
  source "$HOME/robot_ws/install/setup.bash"
  export ROS_DOMAIN_ID=42
  export ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST
}

setup.bash를 찾지 못하면 Build가 안 된 것인지, 경로가 다른 것인지부터 확인합니다. Source 오류를 숨기기 위해 2>/dev/null을 붙이지 않습니다.

10. 첫 Workspace와 Package를 만든다

설치 확인은 빈 Workspace Build보다 실제 최소 Package를 만드는 편이 더 강력합니다.

mkdir -p "$HOME/robot_ws/src"
cd "$HOME/robot_ws/src"

ros2 pkg create env_check \
  --build-type ament_python \
  --dependencies rclpy std_msgs \
  --node-name environment_check

cd "$HOME/robot_ws"
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install --packages-select env_check
source install/setup.bash
ros2 run env_check environment_check

검증 Point:

1. ros2 pkg create — Package Template와 Python 도구가 정상입니다.
2. rosdep install — OS Dependency Database와 Package Metadata가 정상입니다.
3. colcon build — Build Tool, Compiler·Python Packaging이 정상입니다.
4. source install/setup.bash — Overlay가 정상 생성됐습니다.
5. ros2 run — Package Index와 Entry Point가 정상입니다.

# Build 결과와 Test 확인
colcon test --packages-select env_check
colcon test-result --verbose

# 어떤 Prefix에서 Package를 찾았는지 확인
ros2 pkg prefix env_check

11. Docker 개발 환경을 재현 가능하게 만든다

Container는 OS User Space와 Dependency를 고정하지만 Host Kernel, GPU Driver, USB와 Network까지 격리하거나 자동 해결하지는 않습니다.

# Dockerfile — 팀이 검증한 정확한 Tag 또는 Digest를 사용한다.
ARG ROS_DISTRO=<배포판>
FROM ros:${ROS_DISTRO}-ros-base

SHELL ["/bin/bash", "-c"]

RUN apt-get update && apt-get install -y --no-install-recommends \
      python3-colcon-common-extensions \
      python3-rosdep \
      ros-dev-tools \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /workspace
COPY src /workspace/src

RUN source "/opt/ros/${ROS_DISTRO}/setup.bash" \
    && rosdep install --from-paths src --ignore-src -r -y \
    && colcon build --merge-install

COPY docker/entrypoint.sh /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
CMD ["bash"]

#!/usr/bin/env bash
# docker/entrypoint.sh
set -e
source "/opt/ros/${ROS_DISTRO}/setup.bash"
if [[ -f /workspace/install/setup.bash ]]; then
  source /workspace/install/setup.bash
fi
exec "$@"

Container 실행에서 결정할 것

• User ID: Root로 생성한 Build·Log File이 Host에서 수정 불가능해지지 않도록 UID/GID를 맞춥니다.
• Network: Host Network는 Linux에서 편하지만 격리 범위가 넓어집니다. Team 보안 정책과 DDS Discovery 방식을 검토합니다.
• Device: 필요한 /dev/...만 명시적으로 전달합니다. --privileged를 기본 해결책으로 쓰지 않습니다.
• GUI: Wayland·X11 Socket, Display 인증과 GPU Runtime을 Host 환경에 맞춥니다.
• Persistence: Source, Build Cache와 Bag Data 중 무엇을 Volume으로 유지할지 정합니다.

# Image에 포함된 환경을 확인하는 비파괴적 점검 예
docker run --rm ros:<배포판>-ros-base \
  bash -lc 'source /opt/ros/<배포판>/setup.bash && ros2 --help >/dev/null && echo OK'

Image Tag만 사용하면 시간이 지나 같은 Tag 내용이 바뀔 수 있습니다. Release 환경은 Digest, Lock File, Build 날짜와 SBOM을 함께 관리합니다.

12. VS Code와 정적 분석 도구를 연결한다

IDE가 ROS Package를 찾으려면 ROS Environment가 적용된 Shell에서 실행하거나 설정에 Python·CMake 경로를 알려야 합니다.

권장 기능:

• Python: Ruff 또는 Flake8, Black, mypy·Pyright
• C++: clangd, clang-format, clang-tidy
• ROS: package.xml, CMakeLists.txt, Launch·YAML 편집 지원
• Container: Dev Containers 또는 Remote SSH

# Workspace 환경을 적용한 Terminal에서 VS Code 실행
source /opt/ros/<배포판>/setup.bash
source "$HOME/robot_ws/install/setup.bash"
code "$HOME/robot_ws"

# Python 문법·Style과 Test
python3 -m compileall src
colcon test --event-handlers console_direct+
colcon test-result --verbose

# CMake가 내보낸 compile_commands.json을 clangd에 제공
colcon build --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

IDE에서 Import Error 표시가 나지만 Terminal 실행은 된다면 IDE가 다른 Python Interpreter나 Environment를 사용하고 있는지 확인합니다. 반대로 IDE 표시만 없애려고 Global PYTHONPATH를 무리하게 추가하면 실제 Runtime과 다른 환경이 만들어질 수 있습니다.

13. USB·Serial·Camera Device 권한을 설정한다

Device 문제를 ROS 문제로 보기 전에 OS 계층부터 확인합니다.

# USB 장치 식별
lsusb
lsusb -t

# 연결 직후 Kernel Event 확인
journalctl -k --since '2 minutes ago'

# Serial 장치와 권한
ls -l /dev/ttyUSB* /dev/ttyACM* 2>/dev/null
groups

# Camera Device
ls -l /dev/video* 2>/dev/null

Serial Group은 Distribution에 따라 dialout, Camera는 video인 경우가 많습니다. 사용자를 필요한 Group에 추가한 뒤 새 Login Session이 필요합니다. 모든 Device를 chmod 777로 여는 방식은 사용하지 않습니다.

udev Rule은 Product 이름이 아니라 Vendor ID, Product ID와 가능하면 Serial Number를 사용해 안정된 Symbolic Link를 만듭니다.

# /etc/udev/rules.d/99-my-lidar.rules — 값은 실제 lsusb/udevadm 결과로 교체
SUBSYSTEM=="tty", ATTRS{idVendor}=="1234", ATTRS{idProduct}=="5678", \
  ATTRS{serial}=="ABC123", GROUP="dialout", MODE="0660", \
  SYMLINK+="my_lidar"

# 실제 속성 확인
udevadm info --attribute-walk --name=/dev/ttyUSB0

# Rule 문법·적용 결과 시험
udevadm test "$(udevadm info -q path -n /dev/ttyUSB0)"

Rule 적용과 Group 변경은 System 권한 변경입니다. 대상 Device와 Rule을 검토하고 기존 Rule과 충돌하지 않는지 확인합니다.

14. Network와 Clock을 개발환경의 일부로 본다

ROS 2 Discovery 문제는 Application Code보다 Network 정책에서 발생하는 경우가 많습니다.

# Interface와 Route
ip -brief address
ip route

# Host 이름과 DNS
hostnamectl
getent hosts <상대-host-name>

# 방화벽 상태만 확인
sudo ufw status verbose

# ROS 환경 비교
printenv | rg '^(ROS|RMW|CYCLONEDDS|FAST)'

# Middleware 이전 Multicast 시험
ros2 multicast receive   # Computer A
ros2 multicast send      # Computer B

회사·학교 Wi-Fi의 Client Isolation, VPN, Container NAT, 여러 Network Interface와 Firewall은 Discovery를 막을 수 있습니다. 보안을 위해 Firewall 전체를 끄기보다 사용 중인 RMW의 공식 Network 요구사항에 맞춰 최소 Rule을 설계합니다.

Clock이 다르면 TF Extrapolation, Sensor Fusion 오류와 Log 사건 순서 왜곡이 생깁니다.

timedatectl status
date --iso-8601=ns

# chrony를 사용하는 환경 예시
chronyc tracking
chronyc sources -v

일반 Robot은 NTP·chrony, 더 엄격한 Sensor 동기화는 Hardware Timestamp와 PTP를 검토합니다. /clock을 쓰는 Simulation·Bag 재생과 System Time 동기화를 혼동하지 않습니다.

15. 설치 검증 Report를 자동으로 수집한다

다음 Script는 환경을 변경하지 않고 도움 요청에 필요한 정보를 모읍니다. Token과 내부 주소가 Environment에 들어 있을 수 있으므로 전체 printenv를 그대로 공유하지 않습니다.

#!/usr/bin/env bash
set -u

echo '== OS =='
uname -a
sed -n '1,8p' /etc/os-release

echo '== ROS environment =='
for name in ROS_DISTRO ROS_VERSION ROS_DOMAIN_ID \
            ROS_AUTOMATIC_DISCOVERY_RANGE ROS_LOCALHOST_ONLY \
            RMW_IMPLEMENTATION; do
  printf '%s=%s\n' "$name" "${!name-<unset>}"
done

echo '== Commands =='
command -v ros2 || true
command -v colcon || true
command -v rosdep || true

echo '== Installation =='
ls -1 /opt/ros 2>/dev/null || true

if command -v ros2 >/dev/null 2>&1; then
  echo '== ROS doctor =='
  ros2 doctor --report || true
fi

echo '== Network =='
ip -brief address
ip route

echo '== Disk =='
df -h

Report에는 실행한 명령, 정확한 Error 전문, 기대 결과와 실제 결과를 함께 적습니다. Screenshot보다 검색 가능한 Text가 좋고 Secret·사용자 이름·내부 IP는 공유 범위에 맞게 가립니다.

16. 계층별 문제 해결표

진단 원칙은 가장 아래 계층부터 하나씩 증명하는 것입니다. Camera Node가 안 뜬다고 ROS Package부터 다시 설치하지 말고 OS가 Device를 보는지, 권한이 있는지, Driver Process가 열 수 있는지를 먼저 확인합니다.

17. 확인 퀴즈 15문항

1. 실무에서 ROS 2 개발 환경으로 Ubuntu가 사실상 표준인 이유로 옳지 않은 것은?

• (1) 공식 바이너리가 Ubuntu용으로 가장 완전하게 제공된다
• (2) 서드파티 패키지의 설치 안내가 대부분 apt 기준이다
• (3) 로봇에 실제로 올라가는 것도 대개 Ubuntu 계열이다
• (4) 다른 운영체제에서는 ROS 2가 아예 동작하지 않는다 정답

해설: ROS 2는 다른 운영체제도 지원하므로 아예 동작하지 않는다는 설명은 틀립니다. Ubuntu가 표준인 것은 기술적 제약이 아니라 바이너리 제공, 서드파티 문서, 배포 환경 일치라는 현실적인 이유 때문입니다.

2. 실제 로봇 하드웨어를 붙일 계획이라면 가장 권장되는 환경은?

• (1) 가상머신
• (2) 네이티브 Ubuntu 정답
• (3) WSL2
• (4) 어느 것이든 동일하다

해설: USB 직결 센서, 실시간성, GPU 접근에서 네이티브 Ubuntu가 가장 유리하고, 배포 환경과 개발 환경이 같아져 "내 컴퓨터에서는 됐는데"가 줄어듭니다. WSL2와 가상머신은 하드웨어 접근과 성능에서 제약이 있습니다.

3. Docker를 ROS 2 개발 환경으로 쓸 때의 가장 큰 장점은?

• (1) GUI 설정이 필요 없다
• (2) 여러 배포판을 동시에 쓸 수 있고 환경이 꼬여도 컨테이너만 지우면 된다 정답
• (3) USB 장치가 자동으로 연결된다
• (4) 네이티브보다 빠르다

해설: 환경 격리가 Docker의 핵심 가치입니다. 배포판을 여러 개 오가거나 팀 전체가 동일한 환경을 쓰게 만들 때 특히 유용합니다. 다만 GUI와 USB 장치는 추가 설정이 필요하므로 그 점은 장점이 아닙니다.

4. ROS 2 배포판을 고를 때 권장되는 방식은?

• (1) 항상 가장 최신 배포판을 쓴다
• (2) 지원 기간, Ubuntu 조합, 필요한 Driver와 팀 검증 결과를 공식 문서로 확인한다 정답
• (3) 가장 오래된 배포판을 쓴다
• (4) 배포판은 아무거나 상관없다

해설: 무조건 최신 또는 이전 세대를 고르는 규칙은 없습니다. 제품 수명, OS 지원, Security Update, 필요한 Sensor·GPU·Nav2·MoveIt Package와 팀의 Test 결과를 함께 확인하고 검증된 조합을 고정합니다.

5. ROS 2 배포판과 Ubuntu 버전의 관계로 옳은 것은?

• (1) 어떤 Ubuntu 버전에서든 아무 배포판이나 설치할 수 있다
• (2) 배포판마다 지원하는 Ubuntu 버전이 정해져 있어 짝이 맞지 않으면 설치되지 않는다 정답
• (3) Ubuntu 버전은 성능에만 영향을 준다
• (4) 배포판이 Ubuntu 버전을 자동으로 바꿔 준다

해설: 각 배포판은 특정 Ubuntu 버전을 대상으로 빌드되어 배포되므로, 짝이 맞지 않으면 apt 저장소에 그 패키지가 아예 없습니다. 정확한 조합과 EOL 날짜는 시간에 따라 바뀌므로 반드시 공식 문서에서 확인해야 합니다.

6. 설치 절차에서 로케일을 UTF-8로 설정하는 이유는?

• (1) 설치 속도가 빨라지기 때문
• (2) 한글이 섞인 로그나 파일 이름에서 생기는 오류를 막기 위해 정답
• (3) apt 저장소가 UTF-8을 요구하기 때문
• (4) DDS가 UTF-8만 지원하기 때문

해설: 로케일이 UTF-8이 아니면 비영문 문자가 포함된 로그, 파일 이름, 메시지에서 인코딩 오류가 발생할 수 있습니다. 한국어 환경에서는 특히 빠뜨리지 말아야 하며, 나중에 원인을 찾기 어려운 종류의 문제로 나타납니다.

7. ros-<배포판>-desktop 대신 ros-<배포판>-ros-base를 쓰는 상황은?

• (1) 개발용 PC에 설치할 때
• (2) GUI가 필요 없는 로봇 본체에 설치해 용량을 줄일 때 정답
• (3) RViz2를 쓰고 싶을 때
• (4) 시뮬레이션을 돌릴 때

해설: desktop 묶음은 RViz2와 데모까지 포함해 용량이 큽니다. 로봇에 올라가는 컴퓨터에는 GUI가 필요 없으므로 ros-base로 설치하면 저장 공간과 설치 시간을 크게 아낄 수 있습니다.

8. "설치를 마쳤는데 colcon 명령이 없다"의 원인은?

• (1) source를 하지 않았다
• (2) 개발 도구(colcon 확장)를 설치하지 않았다 정답
• (3) Ubuntu 버전이 맞지 않는다
• (4) rosdep을 실행하지 않았다

해설: ROS 2 본체 패키지만 설치하면 빌드 도구는 함께 오지 않습니다. ros-dev-tools 또는 python3-colcon-common-extensions를 별도로 설치해야 colcon 명령을 쓸 수 있습니다. 설치 안내에서 가장 자주 건너뛰는 단계입니다.

9. rosdep update를 sudo로 실행하면 어떤 문제가 생기는가?

• (1) 아무 문제도 없다
• (2) 캐시 소유자가 root가 되어 나중에 권한 오류가 난다 정답
• (3) 데이터베이스가 손상된다
• (4) 설치가 취소된다

해설: rosdep의 캐시는 사용자 홈 아래에 만들어지는데 sudo로 실행하면 root 소유가 되어 이후 일반 계정의 rosdep이 접근하지 못합니다. init만 sudo로 하고 update는 사용자 계정으로 실행해야 하며, 꼬였다면 캐시를 지우고 다시 하면 됩니다.

10. 설치 확인 단계에서 talker와 listener 데모가 특히 값어치 있는 이유는?

• (1) 가장 빠르게 끝나기 때문
• (2) 미들웨어, 디스커버리, 직렬화가 모두 정상임을 한 번에 확인해 주기 때문 정답
• (3) GUI를 확인할 수 있기 때문
• (4) 빌드 도구를 확인할 수 있기 때문

해설: 두 노드가 서로를 발견하고 메시지를 주고받는다는 것은 DDS 디스커버리, 직렬화, 전송이 모두 동작한다는 뜻입니다. 여기까지 되면 ROS 2의 핵심 경로가 살아 있음을 확인한 것이므로, 이후 문제는 대개 사용자 코드나 설정 쪽입니다.

11. 같은 네트워크에서 옆 사람의 노드와 섞이지 않게 하는 가장 기본적인 수단은?

• (1) RMW_IMPLEMENTATION을 바꾼다
• (2) ROS_DOMAIN_ID를 각자 다르게 정한다 정답
• (3) QoS를 BEST_EFFORT로 바꾼다
• (4) 노드 이름을 길게 짓는다

해설: 같은 Discovery 범위에서 같은 ROS_DOMAIN_ID를 공유하면 옆 사람의 Node와 연결될 수 있습니다. 유효·권장 범위는 OS의 DDS Port와 Ephemeral Port 조건을 확인하고 조직에서 충돌하지 않게 배정합니다.

12. Discovery 범위를 LOCALHOST로 두면 안 되는 상황은?

• (1) 혼자 한 대에서 실습할 때
• (2) 두 대 이상의 컴퓨터로 통신 실험을 할 때 정답
• (3) 시뮬레이션을 돌릴 때
• (4) 로그를 기록할 때

해설: Localhost 범위에서는 다른 Computer의 Node를 자동 발견하지 못합니다. 최신 배포판의 ROS_AUTOMATIC_DISCOVERY_RANGE·ROS_STATIC_PEERS 또는 구형 배포판 설정을 확인해 Subnet이나 명시적 Peer 정책을 구성해야 합니다.

13. RMW_IMPLEMENTATION을 바꿔 통신 문제를 비교할 때 먼저 해야 할 것은?

• (1) 한 노드씩 순서대로 바꾼다
• (2) 관련 Process를 같은 구현으로 맞춰 다른 변수를 줄인 뒤 별도 상호운용성을 시험한다 정답
• (3) 반드시 재설치해야 한다
• (4) QoS도 함께 바꿔야 한다

해설: DDS Vendor 간 통신은 표준 Protocol을 목표로 하지만 설정과 기능 차이가 있을 수 있습니다. 원인 비교에서는 먼저 같은 RMW로 통일해 변수를 줄이고, 다른 Vendor 조합이 요구되면 Discovery·QoS·Security와 Data Type을 별도 Test합니다.

14. 다른 컴퓨터의 노드가 보이지 않을 때 ROS 2 이전 단계에서 네트워크 자체를 확인하는 명령은?

• (1) ros2 doctor
• (2) ros2 multicast send 와 ros2 multicast receive 정답
• (3) ros2 topic list
• (4) ros2 daemon stop

해설: multicast 송수신이 되는지 확인하면 문제가 ROS 2에 있는지 네트워크에 있는지 바로 갈립니다. 여기서 실패하면 방화벽, 서브넷 불일치, Wi-Fi의 클라이언트 격리 같은 네트워크 문제이므로 ROS 설정을 아무리 고쳐도 소용없습니다.

15. .bashrc에 넣지 않는 편이 안전한 것은?

• (1) underlay source 줄
• (2) ROS_DOMAIN_ID 설정
• (3) 워크스페이스 overlay source 줄 정답
• (4) LANG 설정

해설: 워크스페이스가 여러 개가 되면 어느 overlay가 켜져 있는지 헷갈리고, 빌드하기 전 상태의 환경이 필요할 때 곤란해집니다. underlay와 도메인 ID 정도만 넣고 overlay는 그때그때 필요한 터미널에서 직접 source 하는 편이 안전합니다.

연습 문제

1. Native Ubuntu, Docker, WSL2와 Virtual Machine을 실제 Robot 개발 관점에서 비교하세요.
2. ROS 2 Distribution과 Ubuntu Version을 선택할 때 확인해야 할 기준을 설명하세요.
3. 설치 전에 작성할 환경 명세 항목과 각각의 목적을 쓰세요.
4. Desktop과 ROS Base 설치 Variant의 차이와 선택 기준을 설명하세요.
5. Apt Source 등록에서 오래된 Blog 명령보다 공식 설치 문서를 사용해야 하는 이유는 무엇인가요?
6. Underlay와 Overlay의 Source 순서가 Package 선택에 미치는 영향을 설명하세요.
7. 최소 Package 생성·rosdep·colcon·ros2 run이 각각 검증하는 계층은 무엇인가요?
8. Docker가 재현하는 범위와 자동으로 해결하지 못하는 Host 의존성을 설명하세요.
9. ROS 2 Container에서 --privileged를 기본 해결책으로 사용하면 안 되는 이유는 무엇인가요?
10. IDE의 Import Error와 실제 Runtime 환경이 다를 때 진단하는 방법을 설명하세요.
11. USB Serial Device에 안정된 udev Symbolic Link를 만드는 기준을 쓰세요.
12. ROS_DOMAIN_ID와 Discovery Range의 역할 차이를 설명하세요.
13. 다른 Computer의 Node가 보이지 않을 때 Network부터 DDS까지 진단 순서를 쓰세요.
14. Clock 동기화가 TF, Sensor Fusion과 Log 분석에 필요한 이유는 무엇인가요?
15. 설치 검증 Report에 포함할 정보와 외부 공유 전에 제거할 정보를 설명하세요.

참고 자료

• ROS 2 Distributions
• ROS 2 Installation
• Ubuntu binary installation 안내
• Configuring ROS 2 environment
• Using ros2doctor to identify issues
• The ROS_DOMAIN_ID
• Improved Dynamic Discovery
• rosdep documentation
• colcon documentation