3.10 환경 점검 체크리스트 · 인터랙티브 콘텐츠

시뮬레이션과 실기기 단계에서 막힐 때 원인은 사실 개발환경 문제인 경우가 많습니다. 코드를 짜기 전에 환경이 정상인지 한 번에 점검해 두면 시간을 많이 아낄 수 있습니다. 이 장의 체크리스트는 이후에도 "뭔가 이상한데" 싶을 때 다시 열어 보라고 만든 것입니다.

환경 점검 체크리스트

각 항목의 명령을 VM의 Tilix에서 실행하고 기대 결과와 같으면 체크하세요. 체크 상태는 이 브라우저에 저장되어 다시 열어도 유지됩니다. (브라우저가 저장을 막은 경우에는 페이지를 닫으면 초기화됩니다. 동작에는 문제없습니다.)

진행 상황: 0 / 17

1) 가상머신 (VM)

Ubuntu 22.04가 설치되어 있다
```
$ lsb_release -a
```
기대 결과: Description 줄에 Ubuntu 22.04.x LTS, Codename 줄에 jammy
막히면 3.1장으로 돌아가세요.
CPU 아키텍처를 확인했다
```
$ uname -m
```
기대 결과: x86_64 (Windows PC의 일반적인 VM). 다른 값이면 강사에게 문의
막히면 3.1장으로 돌아가세요.
VM에서 인터넷에 접속된다
```
$ ping -c 3 8.8.8.8
```
기대 결과: 마지막 줄 근처에 0% packet loss
막히면 3.9장으로 돌아가세요.
디스크 여유 공간이 충분하다
```
$ df -h /
```
기대 결과: Avail 열이 수 GB 이상 남아 있음 (OVA는 25 GB 중 약 15 GB를 쓰고 8 GB 남짓 남습니다. 빌드 결과가 계속 쌓입니다)
막히면 3.1장으로 돌아가세요.

2) ROS2 설치

ROS2 환경이 적용된다 (source 됨)
```
$ printenv | grep '^ROS'
```
기대 결과: ROS_VERSION=2, ROS_PYTHON_VERSION=3, ROS_DISTRO=humble 이 포함됨 (ROS_LOCALHOST_ONLY=0도 보임. 0은 꺼진 상태)
막히면 3.4장으로 돌아가세요.
ros2 명령이 동작한다
```
$ ros2 pkg list | sed -n '1,5p'
```
기대 결과: 패키지 이름이 몇 줄 출력됨 (Command not found 가 아님)
막히면 3.4장으로 돌아가세요.
데모 talker가 실행된다
```
$ ros2 run demo_nodes_cpp talker
```
기대 결과: Publishing: 'Hello World: 1' 같은 로그가 계속 출력됨 (Ctrl+C로 종료)
막히면 3.5장으로 돌아가세요.
colcon이 설치되어 있다
```
$ colcon --help
```
기대 결과: usage 안내가 출력됨 (command not found 가 아님)
막히면 3.4장으로 돌아가세요.
새 터미널에서도 자동으로 source 된다
```
$ grep -n 'setup.bash' ~/.bashrc
```
기대 결과: source /opt/ros/humble/setup.bash 줄과 source ~/ros2_ws/install/setup.bash 줄이 나옴 (OVA는 120번, 121번 줄)
막히면 3.4장으로 돌아가세요.

3) 워크스페이스

워크스페이스가 있고 빌드되어 있다
```
$ ls ~/ros2_ws
```
기대 결과: build install log src 네 폴더가 보임
막히면 3.7장으로 돌아가세요.
OVA의 TIKI-MINI 패키지가 인식된다
```
$ ros2 pkg list | grep tiki
```
기대 결과: tiki_navigation 과 tiki_slam 두 줄 (아무것도 안 나오면 새 터미널을 열거나 source ~/ros2_ws/install/setup.bash)
막히면 3.11장으로 돌아가세요.
(3.7장을 했다면) 내 패키지의 실행 파일이 등록되어 있다
```
$ ros2 pkg executables my_first_pkg
```
기대 결과: my_first_pkg talker (3.7장에서 만든 패키지를 지웠다면 Package not found 가 나오는 것이 정상)
막히면 3.7장으로 돌아가세요.
내 노드의 메시지를 토픽에서 확인했다
```
$ ros2 topic echo /chatter
```
기대 결과: talker를 다른 터미널에서 실행 중일 때 data: ... 가 반복 출력됨
막히면 3.7장으로 돌아가세요.

4) 네트워크

VM의 IP 주소를 확인했다
```
$ ip a
```
기대 결과: 사용 중인 인터페이스에 inet 주소가 있음. OVA의 기본 NAT 모드에서는 10.0.2.15 (enp0s3). 로봇과 연결하는 브리지 모드에서는 192.168.x.x 같은 주소
막히면 3.9장으로 돌아가세요.
ROS_DOMAIN_ID가 나에게 배정된 값이다
```
$ echo $ROS_DOMAIN_ID
```
기대 결과: 강사가 배정한 번호 (OVA는 비어 있고 기본값 0). 교실에서는 겹치지 않아야 함
막히면 3.9장으로 돌아가세요.
ros2 doctor가 치명적 오류 없이 끝난다
```
$ ros2 doctor
```
기대 결과: All <n> checks passed (OVA에서는 패키지가 최신이 아니라는 UserWarning 이 많이 나오지만 괜찮음)
막히면 3.10장으로 돌아가세요.
다른 PC(또는 로봇)와 토픽이 서로 보인다
```
$ ros2 topic list
```
기대 결과: 상대 쪽에서 실행한 노드의 토픽(예: /chatter)이 목록에 나타남
막히면 3.9장으로 돌아가세요.

체크리스트 명령 실행 화면

OVA에서 위 항목의 명령을 이어서 실행한 화면입니다. 먼저 시스템 항목입니다.

lsb_release, uname -m, df -h /, ping 8.8.8.8 실행 결과에 번호 표시

① lsb_release -a: Ubuntu 22.04.5 LTS, 코드명 jammy
② uname -m: x86_64
③ df -h /: 25 GB급 디스크에 7.2G가 남아 있습니다.
④ ping -c 3 8.8.8.8: 0% packet loss

다음은 ROS2와 워크스페이스 항목입니다.

printenv, ros2 pkg list, colcon --help, .bashrc의 setup.bash 줄, ls ~/ros2_ws, tiki 패키지 목록에 번호 표시

① printenv | grep '^ROS': ROS_VERSION=2, ROS_PYTHON_VERSION=3, ROS_DISTRO=humble. ROS_LOCALHOST_ONLY=0도 함께 보이며 0은 꺼진 상태입니다.
② ros2 pkg list의 앞 5줄
③ colcon --help의 usage 안내
④ ~/.bashrc의 120번 줄(ROS2 본체)과 121번 줄(~/ros2_ws)
⑤ ls ~/ros2_ws: build install log src
⑥ ros2 pkg list | grep tiki: tiki_navigation과 tiki_slam

printenv | grep -i ROS처럼 -i를 붙이면 사용자 이름 ros2가 들어간 줄(HOME, PATH 등)까지 모두 걸려 나와 읽기 어렵습니다. '^ROS'로 줄의 맨 앞만 보세요.

ros2 doctor

체크리스트는 "내가 정한 항목"을 확인합니다. ros2 doctor는 ROS2가 스스로 환경을 점검해 주는 도구로, ROS2 공식 튜토리얼에 소개되어 있습니다. 먼저 ROS2를 source한 터미널에서 실행합니다.

ros2 doctor

플랫폼, 버전, 네트워크, 환경변수, 실행 중인 시스템 등을 검사합니다. OVA에서 실행한 실제 출력의 끝부분은 이렇습니다.

ros2 doctor 실행 결과의 끝부분. UserWarning 줄들과 tiki 패키지 경고, All 5 checks passed에 번호 표시

① ros2 doctor 실행. 출력이 길어서 2>&1 | tail -n 7로 끝 7줄만 본 화면입니다.
② UserWarning: ... has been updated to a new version. local: 1.2.1 < latest: 1.2.3: 설치된 ROS 패키지보다 새 버전이 나와 있다는 안내입니다. OVA를 만든 뒤에 업데이트가 나온 것이라 거의 모든 패키지에 뜹니다. 인터넷이 연결되어 있을 때 최신 버전을 조회해서 나옵니다.
③ Cannot find the latest versions of packages: tiki_slam tiki_navigation: TIKI-MINI 패키지는 공개 배포판 목록에 없어서 최신 버전을 찾지 못한다는 뜻입니다. 정상입니다.
④ All 5 checks passed: 검사 5개를 모두 통과했습니다. 경고가 수십 줄 있어도 이 줄이 있으면 환경은 쓸 수 있습니다.

출력 읽는 법

정상: 마지막에 다음 형태의 줄이 나옵니다.

All <n> checks passed

경고(Warning): UserWarning: ... 형태로 출력되는 줄입니다. 공식 문서 설명으로는 대부분의 문제가 경고로 표시되고, 경고만 있다고 해서 환경을 못 쓰는 것은 아닙니다. 경고만 있어도 마지막에 All <n> checks passed가 나올 수 있습니다. 경고 문구를 읽고 의미를 파악해 두세요.

오류(Error): UserWarning: ERROR:로 표시됩니다. 마지막에는 실패한 검사 수(예: 1/3 checks failed)와 실패한 모듈(예: Failed modules: network)이 함께 나옵니다. 중요한 설정이 빠져 있다는 뜻이므로 고쳐야 합니다.

출력	의미	할 일
`All <n> checks passed`	점검 통과	없음
경고(`UserWarning: ...`)	주의 사항	문구를 읽고 의도한 상태인지 판단
`ERROR`, `checks failed`, `Failed modules: ...`	중요한 문제	실패한 모듈(예: network)에 해당하는 항목 점검
`Publisher without subscriber detected on /...`	토픽을 발행하는 노드는 있는데 받는 노드가 없음	노드를 실행 중일 때만 나옴. 받는 쪽을 실행하면 사라짐. 문제가 아닐 수 있음
`Subscriber without publisher detected on /...`	구독하는 노드는 있는데 발행하는 노드가 없음	발행하는 노드가 실행 중인지, 토픽 이름과 `ROS_DOMAIN_ID`가 같은지 확인

위 마지막 두 줄은 ROS2 노드가 실행 중일 때 나타나는 메시지입니다. 위 화면은 실행 중인 노드가 없는 상태에서 찍었으므로 이 두 줄이 없습니다. 예를 들어 3.7장의 talker만 실행해 둔 상태에서 ros2 doctor를 실행하면 /chatter에 대한 발행자는 있고 구독자가 없으니 앞의 경고가 나올 수 있습니다. 이때 다른 터미널에서 ros2 topic echo /chatter를 실행하면 사라집니다. 이 메시지는 정보 제공용이며 오류로 보지 않아도 됩니다.

자세한 보고서

ros2 doctor --report

공식 문서에 적힌 대로 이 보고서는 다섯 부분으로 나뉩니다. 이 VM에서 실제로 실행한 결과입니다. 보고서는 패키지별 버전 목록 때문에 3백 줄이 넘습니다. 화면에는 필요한 부분만 보이도록 파일로 저장한 뒤 각 부분을 찾았습니다.

ros2 doctor --report > /tmp/report.txt

| head로 줄이면 파이프가 먼저 닫혀서 BrokenPipeError가 출력됩니다. 보고서가 잘못된 것은 아니니 파일로 저장해서 읽으세요.

ros2 doctor 보고서의 다섯 섹션 제목과 값. 네트워크, 플랫폼, RMW, ROS 2 정보, 토픽 목록에 번호 표시

① NETWORK CONFIGURATION: 인터페이스별 주소. 첫 줄은 127.0.0.1(loopback)입니다.
② PLATFORM INFORMATION: Linux-6.8.0-51-generic-x86_64-with-glibc2.35
③ RMW MIDDLEWARE: rmw_fastrtps_cpp
④ ROS 2 INFORMATION: distribution name: humble, 지원 플랫폼에 ubuntu: jammy
⑤ TOPIC LIST: 실행 중인 노드가 없으면 토픽 0개, 발행자와 구독자도 0

섹션	내용
NETWORK CONFIGURATION	네트워크 인터페이스 정보
PLATFORM INFORMATION	운영체제와 시스템 정보
RMW MIDDLEWARE	사용 중인 DDS 구현
ROS 2 INFORMATION	ROS2 배포판 정보 (`ROS_DISTRO` 등)
TOPIC LIST	현재 보이는 토픽 목록

강사에게 도움을 요청하거나 네트워크 문제를 추적할 때 이 출력을 통째로 복사해서 전달하면 무엇이 문제인지 파악하기 쉽습니다. 문서 설명대로 ros2 doctor는 코드의 오류를 찾아 주는 디버깅 도구가 아니라 환경 설정을 점검하는 도구입니다.

문제가 생겼을 때: 어디로 돌아갈까

증상별로 가장 먼저 의심할 곳과 돌아갈 장을 정리했습니다. 장 번호는 이 매뉴얼의 번호입니다.

증상	가장 흔한 원인	돌아갈 곳
`ros2: command not found`	ROS2 환경을 source하지 않았거나 `.bashrc` 등록 누락	3.4장의 source 설정 (OVA는 `~/.bashrc` 120번 줄에 이미 있음)
`lsb_release`에서 22.04가 아님	OVA가 아닌 다른 이미지를 가져옴	3.1장의 OVA 가져오기
VM에서 인터넷이 안 됨	VM 네트워크 모드, 호스트 네트워크 문제	3.9장의 IP, ping 확인 순서
VM이 너무 느리거나 멈춤	VM에 할당한 CPU, 메모리 부족	3.1장의 막혔을 때 표
`colcon: command not found`	새 터미널이 아니거나 환경 미적용	3.4장. OVA에는 colcon이 설치되어 있음
`Package 'my_first_pkg' not found`	워크스페이스를 source하지 않음, 빌드 실패	3.7장의 "자주 만나는 실패", 개념은 3.6장
`No executable found`	entry point 철자 오류, 등록 누락, 재빌드 안 함	3.7장 4단계, 3.6장의 entry points
코드를 고쳤는데 반영되지 않음	재빌드, 저장, source 누락	3.7장의 "코드를 고치고 다시 실행하기"
다른 컴퓨터의 노드가 `ros2 topic list`에 안 보임	`ROS_DOMAIN_ID` 불일치, `ROS_LOCALHOST_ONLY=1`, 멀티캐스트 차단	3.9장의 "점검 순서", 개념은 1.8장
남의 노드가 내 목록에 섞여 보임	같은 `ROS_DOMAIN_ID`를 쓰고 있음	3.9장의 `ROS_DOMAIN_ID`
거북이 창이나 rqt를 열 때 `Ignoring XDG_SESSION_TYPE=wayland` 경고	Ubuntu의 화면 방식 안내	무시해도 됨. 창이 뜨면 정상 (3.5장)
`ros2 pkg list` 결과에 tiki가 없음	워크스페이스 미적용, 또는 OVA가 아닌 환경	새 터미널을 열고 `source ~/ros2_ws/install/setup.bash` (3.4장, 3.11장)
`ros2 doctor`에서 network 실패	네트워크 인터페이스, 멀티캐스트 문제	3.9장

한눈에 정리

개발환경은 VM, ROS2 설치, 워크스페이스, 네트워크 네 영역으로 나눠 명령으로 점검한다.
ros2 doctor는 환경 점검 도구이고 마지막 줄 All <n> checks passed 와 ERROR 표시를 먼저 본다. 경고만 있는 것은 괜찮을 수 있다.
ros2 doctor --report는 네트워크, 플랫폼, RMW, ROS2 정보, 토픽 목록을 한 번에 보여 주므로 도움을 요청할 때 유용하다.
증상별로 돌아갈 장을 알아 두면, 처음부터 다시 하지 않고 필요한 곳만 고칠 수 있다.

확인 문제

Q1. ros2 doctor 출력에 UserWarning 줄이 수십 개 있지만 마지막 줄은 All checks passed 입니다. 환경은 사용할 수 있나요?

네, 사용할 수 있습니다. 공식 문서도 경고만 있는 경우에 All <n> checks passed가 나오기도 하고 경고는 대부분 주의 사항이라고 안내합니다. 다만 경고 문구가 의도한 상태인지 읽어 보는 것이 좋습니다. 반면 ERROR나 checks failed가 나오면 고쳐야 합니다.

Q2. 3.7장에서 만든 패키지를 확인하는 ros2 pkg list | grep my_first_pkg 항목에서 아무것도 출력되지 않습니다. 어떤 순서로 점검하나요?

이 터미널에서 source ~/ros2_ws/install/setup.bash를 했는지 확인하고 다시 실행해 봅니다. (OVA는 새 터미널을 열면 자동으로 됩니다.)
그래도 안 되면 colcon build가 성공했는지(Summary 줄), 패키지 폴더가 ~/ros2_ws/src 안에 있는지 확인합니다.
3.7장의 "깔끔하게 다시 빌드"를 시도합니다.

Q3. 두 컴퓨터에서 ROS_DOMAIN_ID도 같고 ping도 되는데 서로의 토픽이 안 보입니다. 이 장의 어떤 도구로, 어느 장의 어떤 점검을 하나요?

3.9장의 점검 순서를 따릅니다. ros2 multicast send/receive로 멀티캐스트가 통과하는지, ROS_LOCALHOST_ONLY가 꺼져 있는지, 방화벽(ufw) 상태를 확인하고 ros2 doctor --report의 NETWORK CONFIGURATION도 살펴봅니다.

다음 장

개발환경 구축이 끝났습니다. 다음 파트에서는 시뮬레이션 환경에서 TIKI-MINI를 움직이고 직접 코드를 작성해 봅니다.