부록 부록

A.4 부록 D — ROS2 Humble·Gazebo 환경 트러블슈팅

부록 · 참조. 0.3·7.1의 설치·실행에서 막히는 곳을 모았다. ⚠️ 명령·증상은 환경·버전에 민감하니 공식 문서가 최종 권위(0.3.1). 일부 항목은 이 책의 컨테이너 검증에서 실제 겪은 것.

A.4.1 설치·배포판

증상	원인 / 해결
`apt`가 `ros-humble-*`를 못 찾음	Ubuntu가 22.04가 아님(배포판 불일치, 0.3.2.1) 또는 저장소 미등록. 22.04 확인: `lsb_release -a`
24.04인데 Humble 필요	Humble=22.04. 듀얼부팅/VM/Docker(`ros:humble`)로 22.04, 또는 ROS2 Jazzy로(패키지명 차이 감안)
저장소 키·GPG 오류	ROS가 `ros2-apt-source` .deb 방식으로 이동 중 — *공식 설치 페이지의 현재 명령* 사용(0.3.5.2)
`pip install`이 externally-managed 거부	venv 밖 설치 시도 → `python3 -m venv` 후 활성화(0.3.4)
`pip install slycot` 빌드 실패(`python-control`의 일부 MIMO·극배치 함수만 필요)	Fortran 컴파일러·BLAS 미설치. `sudo apt install gfortran libopenblas-dev && pip install slycot`(또는 `conda install -c conda-forge control slycot`). slycot 없이도 이 책 대부분 예제는 동작 — 특정 함수가 요구할 때만 설치해도 늦지 않다(0.3.4.1·A.3.7)

A.4.2 소싱·실행

증상	원인 / 해결
`ros2: command not found`	`setup.bash` source 안 함(가장 흔함). `source /opt/ros/humble/setup.bash` — 새 셸마다(`~/.bashrc`에 추가)
내 패키지를 `ros2 run`이 못 찾음	overlay 미소싱: `colcon build` 후 `source install/setup.bash` (underlay→overlay 순서)
`ros2 pkg create` 경고	Humble에서는 `--license` 권장(없으면 경고만, 동작은 함 — 컨테이너 검증서 확인)
두 노드가 통신 안 됨	`ROS_DOMAIN_ID` 불일치 또는 DDS 방화벽. 같은 도메인 설정, QoS 호환 확인
컨테이너 두 개(또는 컨테이너↔호스트) 노드가 서로 못 찾음 — 컨테이너 하나 안에서는 `ros2 topic list`가 되는데 컨테이너 간 pub/sub는 타임아웃	Docker 기본 bridge 네트워크가 DDS 디스커버리용 UDP 멀티캐스트를 막음(0.3.5). 로컬 개발은 `docker run --network=host`가 가장 간단. 안 되면 `RMW_IMPLEMENTATION=rmw_cyclonedds_cpp`로 전환(CycloneDDS가 일부 컨테이너 네트워킹을 기본 Fast-DDS보다 관대하게 처리). 멀티 컨테이너/멀티 호스트는 peer 목록·Discovery Server를 명시 설정
노드는 도는데 토픽 비어 있음	QoS 불일치(신뢰성·이력)·이름 오타. `ros2 topic echo /이름`, `ros2 topic info /이름 -v`로 진단

A.4.3 빌드(colcon)

증상	원인 / 해결
`colcon: command not found`	`sudo apt install python3-colcon-common-extensions` (또는 `ros-dev-tools`)
의존성 누락 빌드 실패	`rosdep install --from-paths src --ignore-src -r -y` (최초 `sudo rosdep init; rosdep update`)
ament_python 패키지 노드 인식 안 됨	`setup.py`의 `entry_points`(console_scripts)·`package.xml` 확인, 재빌드
빌드는 됐는데 변경 반영 안 됨	overlay 재소싱, `--symlink-install`로 빌드하면 파이썬 수정 즉시 반영

A.4.4 Gazebo·시각화

증상	원인 / 해결
`gazebo` 검은 화면/매우 느림	그래픽 가속 부족(VM·원격·헤드리스). 네이티브 GPU 환경 권장(0.3.3)
"Gazebo" 튜토리얼이 안 맞음	Classic 11 vs 새 Gazebo(Ignition) 혼동(0.3.7). 패키지: Classic=`gazebo_ros_pkgs`, 새=`ros_gz` — 섞지 말 것
turtlesim/rviz 창 안 뜸(컨테이너)	headless엔 디스플레이 없음. X 포워딩(`-e DISPLAY`·`xhost`)·VNC, 또는 데스크톱 환경에서
Gazebo headless	`gzserver`만(서버) 가능하나 설정 복잡 — 이 책은 제어 로직을 비-GUI로 검증(7.1~7.6)

A.4.5 제어·실시간

증상	원인 / 해결
제어 루프 주기가 불규칙(지터)	`rclpy`/기본 실행기는 경성 실시간 아님(3.3.9·7.1.4). 빠른 루프는 `rclcpp`+실시간 커널 또는 `ros2_control`
`ros2_control` 컨트롤러 로드 실패	URDF의 `ros2_control` 태그·controller YAML·`controller_manager` 설정 확인. 인터페이스(command/state) 이름 일치
제어가 떨림/발산	잡음 미분(필터, 2.5.6.2)·튜닝·샘플링 주기(3.2.3)·지연. 먼저 시뮬레이션에서 검증
추정이 드리프트/발산	칼만 $Q,R$ 튜닝(5.2.7)·각도 wrapping(5.3.7)·프레임/시간 동기(5.4.7)

A.4.6 진단 도구 (먼저 써 볼 것)

ros2 node list                 # 실행 중인 노드
ros2 topic list                # 토픽 목록
ros2 topic echo /이름          # 실제 데이터 흐르나
ros2 topic hz /이름            # 발행 주파수(루프 주기 확인)
ros2 topic info /이름 -v       # pub/sub·QoS 확인
ros2 interface show 타입       # 메시지 구조
ros2 doctor                    # 환경 점검
ros2 bag record /이름          # 데이터 기록(재현·디버깅)

막히면: ① 에러 메시지를 그대로 검색, ② ros2 doctor·위 진단 도구, ③ 공식 문서(docs.ros.org)·ROS Answers. 설치·환경에서 막히는 것은 정상이다(0.3.11) — 이 과정 자체가 실무의 절반.