부록 부록

A.1 CLI 레퍼런스

A.1.1 이 부록의 사용법

이 부록은 "무엇을 할 때 어느 명령을 쓰는가"를 찾기 위한 것이다. 각 명령의 완전한 옵션 목록이 아니라, 실무에서 자주 쓰는 것과 그 명령을 다룬 장으로의 색인이다.

정직: ros2 <명령> <동사> --help가 언제나 정본이다(0.7.1). 옵션 이름·기본값은 배포판에 따라 달라질 수 있다. 다만 이 부록이 다루는 명령·동사가 실재하는지는 Jazzy에서 전수 대조했다(실행 확인, A.1.14) — 이 부록에 있는 동사는 전부 실재하고, 반대로 부록이 빠뜨린 동사 10종을 찾아 보강했다(목차 3). 책 전체가 쓰는 명령 조합 81종·롱플래그 31종·인터페이스 타입 53종도 대조했고 전부 실재했다(실행 확인, A.1.15).

구조(0.7.2): ros2 <명령> <동사> [인자]

A.1.2 상황별 색인 — 무엇을 하려는가

이 표에서 시작하는 것이 가장 빠르다.

A.1.3 topic

ros2 topic list                       # 토픽 목록
ros2 topic list -t                    # 타입 함께
ros2 topic info /scan                 # 발행·구독자 수
ros2 topic info /scan -v              # ★ QoS 포함 — 미연결 진단의 핵심
ros2 topic type /scan                 # 타입 이름
ros2 topic hz /scan --window 20       # 주기 (평균·최소·최대·표준편차)
                                      # 창 기본값은 메시지 10,000개 — 10 Hz 토픽이면 17분을 기억한다(0.7.12.2)
ros2 topic bw /camera/image_raw       # 대역
ros2 topic delay /scan                # 스탬프 기준 지연 (실행 확인)
ros2 topic echo /scan                 # 내용
ros2 topic echo /scan --once          # 한 번만
ros2 topic echo /scan --no-arr        # 배열 생략 (큰 메시지에 유용)
ros2 topic echo /scan --field ranges  # 특정 필드 (실행 확인)
ros2 topic find sensor_msgs/msg/LaserScan   # 타입으로 찾기
ros2 topic pub /cmd_vel geometry_msgs/msg/Twist "{linear: {x: 0.1}}"
ros2 topic pub -1 /cmd_vel ...        # 한 번만
ros2 topic pub -r 10 /cmd_vel ...     # 10 Hz로 반복

ros2 topic pub으로 로봇에 명령을 보낼 때는 로봇이 움직인다는 점에 유의하라(13.1.2).

A.1.4 node·graph

ros2 node list                        # 노드 목록
ros2 node info /my_node               # 발행·구독·서비스·액션·파라미터
ros2 daemon status                    # 데몬 상태 (실행 확인) · start·stop 도 있다
ros2 daemon stop / start              # 데몬 재시작 — 그래프 정보가 이상할 때

ros2 node list에 안 보이면 — 프로세스 종료·ROS_DOMAIN_ID 불일치(1.5.8)·RMW 불일치(3.5.6)·방화벽(3.9.4)·보안 인증 실패(13.3.3) 순으로 확인한다.

A.1.5 param

ros2 param list                       # 전체
ros2 param list /my_node
ros2 param get /my_node rate
ros2 param set /my_node rate 20.0
ros2 param describe /my_node rate     # descriptor (범위·설명)
ros2 param dump /my_node              # ★ 현재 값 전부 — 튜닝 결과 저장
ros2 param load /my_node params.yaml
ros2 param delete /my_node foo        # 실재 (실행 확인)

param set으로 바꾼 값은 재시작하면 사라진다. 좋은 값을 찾았으면 param dump로 저장해 YAML에 반영하라(11.5.5).

A.1.6 service·action·interface

# 서비스
ros2 service list
ros2 service list -t
ros2 service type /set_mode
ros2 service find std_srvs/srv/Trigger
ros2 service call /set_mode my_msgs/srv/SetMode "{mode: 'auto'}"

# 액션
ros2 action list
ros2 action list -t
ros2 action info /navigate_to_pose
ros2 action send_goal /navigate_to_pose nav2_msgs/action/NavigateToPose "{...}"
ros2 action send_goal --feedback /navigate_to_pose ...   # 피드백 표시

# 인터페이스 정의
ros2 interface list
ros2 interface show sensor_msgs/msg/LaserScan
ros2 interface proto sensor_msgs/msg/LaserScan   # 예시 YAML — 실재 (실행 확인)
ros2 interface packages

ros2 interface show가 .msg 정의를 그대로 보여준다 — 필드 이름·타입·주석(단위·프레임 규약)을 확인하는 가장 빠른 방법이다(7.1.6).

A.1.7 bag

ros2 bag record -a                              # 전체
ros2 bag record /scan /tf /tf_static /odom      # 선택
ros2 bag record -o my_bag -a                    # 출력 이름
ros2 bag record -s mcap -a                      # 저장소 지정 (11.2.3)
ros2 bag record -a --max-bag-duration 60        # 시간 분할
ros2 bag record -a --max-bag-size 1000000000    # 크기 분할
ros2 bag record -a --compression-mode file --compression-format zstd
ros2 bag record --qos-profile-overrides-path qos.yaml /scan

ros2 bag info my_bag                            # ★ 기록 직후 반드시 확인
ros2 bag play my_bag
ros2 bag play my_bag --clock                    # ★ 시뮬 시간 발행
ros2 bag play my_bag --rate 0.5
ros2 bag play my_bag --loop
ros2 bag play my_bag --start-offset 30
ros2 bag play my_bag --topics /scan /tf_static  # ★ 충돌 회피
ros2 bag play my_bag --remap /scan:=/scan_replay
ros2 bag convert -i my_bag -o convert.yaml      # 실재 (실행 확인)
ros2 bag reindex my_bag                         # 실재 (실행 확인)

--clock 없이 use_sim_time: true면 시간이 0에 멈춘다(1.10.9). 재생 분석에는 --clock + 전체 노드 use_sim_time: true가 기본이다.

A.1.8 tf2

ros2 run tf2_ros tf2_echo map base_link         # 두 프레임 간 변환
ros2 run tf2_ros tf2_monitor                    # 지연·주기 통계
ros2 run tf2_tools view_frames                  # ★ 트리 PDF 생성
ros2 run tf2_ros static_transform_publisher \
  --x 0.1 --y 0 --z 0.2 --yaw 0 --pitch 0 --roll 0 \
  --frame-id base_link --child-frame-id laser   # (확인 필요: 인자 형식)

view_frames가 tf 문제 진단의 첫 명령이다 — 트리가 끊겼는지, 두 발행자가 충돌하는지(5.1.4), 주기가 적절한지를 한 번에 보여준다.

A.1.9 빌드·실행·패키지

# 빌드 (colcon)
colcon build
colcon build --symlink-install                  # ★ 개발 시 권장
colcon build --packages-select my_pkg
colcon build --packages-up-to my_pkg
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release   # ★ 성능
colcon test --packages-select my_pkg
colcon test-result --verbose                    # ★ 반드시 확인 (14.5.4)
colcon list --topological-order

# rosdep
rosdep install --from-paths src --ignore-src -r -y
rosdep keys --from-paths src --ignore-src

# 실행
ros2 run my_pkg my_node
ros2 run my_pkg my_node --ros-args -p rate:=20.0 -r /scan:=/front_scan
ros2 launch my_pkg my.launch.py
ros2 launch my_pkg my.launch.py use_sim_time:=true
ros2 launch my_pkg my.launch.py --show-args     # ★ 인자 목록
ros2 launch my_pkg my.launch.py --debug

# 패키지
ros2 pkg list
ros2 pkg prefix my_pkg                          # ★ 오버레이 진단 (4.5.8)
ros2 pkg executables my_pkg
ros2 pkg create --build-type ament_cmake my_pkg
ros2 pkg xml my_pkg                             # 실재 (실행 확인)

"고쳤는데 반영이 안 된다"면 ros2 pkg prefix로 실제 경로를 확인하라(11.1.4). 옛 설치본이 실행되고 있을 가능성이 높다.

A.1.10 그 밖의 명령

# 생애주기 (1.12)
ros2 lifecycle nodes
ros2 lifecycle get /my_node
ros2 lifecycle list /my_node
ros2 lifecycle set /my_node configure
ros2 lifecycle set /my_node activate

# 컴포넌트 (2.7)
ros2 component list
ros2 component types
ros2 component load /my_container my_pkg my_pkg::MyComponent
ros2 component unload /my_container 1

# 진단·환경
ros2 doctor                            # 검사 실행 (경고는 기본 무시)
ros2 doctor --report / -r              # 전체 보고서
ros2 doctor --report-failed / -rf      # 실패한 검사만
ros2 doctor --include-warnings / -iw   # 경고도 실패로 취급
ros2 wtf                               # doctor 별칭 (실행 확인)

# 보안 (13.2)
ros2 security create_keystore <path>
ros2 security create_enclave <keystore> <enclave>
ros2 security generate_policy <policy.xml>
ros2 security create_permission <keystore> <enclave> <policy.xml>

# 다중 머신 (3.9)
ros2 multicast send / receive          # 멀티캐스트 확인 (실행 확인)

A.1.11 현장 진단 명령 모음

11.1.3의 체크리스트를 명령으로 정리한 것이다.

# --- 시스템 ---
uptime; df -h; free -h; dmesg | tail -50; ip a; timedatectl

# --- ROS 환경 ---
echo $ROS_DOMAIN_ID; echo $RMW_IMPLEMENTATION; printenv | grep -i ros

# --- 그래프 ---
ros2 node list
ros2 topic list
ros2 topic hz /scan
ros2 topic info /scan -v

# --- 상태 ---
ros2 topic echo /diagnostics_agg --once      # ★ 시스템이 스스로 말한다
ros2 topic echo /rosout | grep -i -E "error|warn"

# --- 좌표 ---
ros2 run tf2_tools view_frames

# --- 파라미터·버전 ---
ros2 param dump /my_node
ros2 pkg prefix my_pkg

이 모음을 스크립트로 만들어 로봇에 미리 넣어 두라(11.1.5). 현장에서 명령을 하나씩 치는 것과 스크립트 하나를 실행하는 것은 압박 상황에서 큰 차이를 만든다.

A.1.12 유용한 조합

# 주기가 불안정한 토픽 찾기
for t in $(ros2 topic list); do echo "== $t"; timeout 5 ros2 topic hz $t; done

# 모든 노드의 파라미터 백업
for n in $(ros2 node list); do ros2 param dump $n > "params_${n//\//_}.yaml"; done

# 대역이 큰 토픽 찾기 (대용량 토픽에서는 부하 주의 — 11.7.5)
ros2 topic bw /camera/image_raw

# 특정 타입을 쓰는 토픽 찾기
ros2 topic find sensor_msgs/msg/PointCloud2

함정: ros2 topic hz·bw는 그 자체로 구독자를 추가한다(11.7.5). 대용량 토픽에서 반복 실행하면 시스템에 부담을 준다 — 관찰자 효과(11.6.7)를 의식하라.

함정 둘: 발행이 멈추면 hz는 아무 말도 하지 않는다 — 마지막 값이 화면에 남은 채 출력만 끊긴다(0.7.12.3). 종료를 판정하는 도구가 아니다.

A.1.14 이 부록이 빠뜨렸던 동사 — 전수 대조 결과

이 부록을 Jazzy에 설치된 실물과 전수 대조했다(실행 확인). 방법은 --help 출력 파싱이 아니라 entry point 조회다 — --help는 데몬 상태에 따라 목록이 덜 나오는 경우가 있어 신뢰할 수 없었다(실제로 ros2 service의 동사가 6종인데 1종만 보이는 일이 있었다).

python3 -c "
from importlib.metadata import entry_points
for ep in entry_points(group='ros2service.verb'): print(ep.name)"

결과: 부록이 다루던 54종은 전부 실재했고, 부록에 없던 동사 15종이 나왔다. 그중 10종은 책 어디에도 없던 것이다. 값어치 순으로 정리한다.

A.1.14.1 ros2 doctor hello — 다중 머신 연결 확인

이름이 장난스러워 지나치기 쉬운데, 다중 호스트 통신 진단 도구다. 실행하면 이런 요약이 1초마다 갱신된다(실행 확인):

MULTIMACHINE COMMUNICATION SUMMARY
Topic: /canyouhearme, Published Msg Count: 10
Subscribed from:
                Hostname             Msg Count /1.0s
Multicast Group/Port: 225.0.0.1/49150, Sent Msg Count: 10
Received from:
                Hostname             Msg Count /1.0s

두 경로를 동시에 본다 — /canyouhearme 토픽(=DDS 정상 경로)과 멀티캐스트(225.0.0.1:49150) 원시 패킷. 두 대 이상에서 동시에 실행하면 서로의 호스트 이름과 수신 개수가 표에 채워진다.

견해: 다중 로봇·원격 PC 문제는 여기서 시작하라. 11.1의 진단 순서에서 "토픽이 안 보인다"의 첫 갈래가 정확히 이 구분(멀티캐스트는 되는데 DDS가 안 되는가)인데, 이 명령 하나가 그 갈래를 바로 보여 준다.

A.1.14.2 ros2 bag burst — 한 걸음씩 재생

ros2 bag burst my_bag -n 1     # 메시지 1개만 내보내고 멈춘다

play가 실시간 흐름을 재현하는 데 반해, burst는 정해진 개수만 내보내고 정지한다(-n/--num-messages). 프레임 단위로 알고리즘 거동을 보거나, 특정 메시지 하나가 어떤 반응을 일으키는지 격리할 때 쓴다 — 11.3의 "재현 가능한 디버깅"에 직접 쓰이는 도구인데 그 장에도 없었다.

A.1.14.3 ros2 bag list · ros2 plugin list — 플러그인이 실제로 뭐가 깔렸나

ros2 bag list storage      # → mcap, sqlite3   (실행 확인)
ros2 bag list converter / compressor / decompressor
ros2 plugin list           # pluginlib 플러그인 전수

ros2 bag list storage는 저장 포맷 플러그인을 보여 준다. 11.2가 MCAP과 sqlite3를 비교하는데, 이 환경에 실제로 어느 쪽이 설치돼 있는지는 이 명령으로만 알 수 있다.

ros2 plugin list는 더 넓다 — pluginlib으로 등록된 모든 플러그인을 패키지별로 출력한다:

rosbag2_storage_mcap:
	mcap [rosbag2_storage_plugins::MCAPStorage] (base: rosbag2_storage::storage_interfaces::ReadWriteInterface)

"플러그인이 연결되지 않는다"류 문제의 첫 명령이 이것이다. 7.2.12에서 본 image_transport 플러그인 누락, 8.5의 Nav2 플러그인 이름 오류, 6.2의 하드웨어 컴포넌트 — 전부 "등록된 이름이 실제로 무엇인가"가 쟁점이었고, 그 답을 이 명령이 준다.

A.1.14.4 ros2 service echo · ros2 service info

ros2 service echo /my_service          # 서비스 요청·응답을 관찰한다
ros2 service info /my_service

토픽에만 echo가 있는 줄 알기 쉬운데 서비스에도 있다. --qos-profile·--qos-depth까지 받는다. 서비스는 요청·응답이 두 노드 사이에서만 오가 관찰하기 어려운데(1.7), 이 명령이 그 벽을 넘는다.

A.1.14.5 나머지

레퍼런스 장에 대한 정직한 고지: 이 부록은 "전형적 형태"를 적어 두었지 전수를 보장하지 않았다 — 실제로 15종이 빠져 있었다. 지금은 Jazzy 기준으로 맞췄지만, 설치 구성에 따라 동사 수가 달라진다. ros2 bag은 ros-jazzy-rosbag2가 없으면 명령 자체가 없고(invalid choice: 'bag'), ros2 security는 sros2가 있어야 나온다. "명령이 없다"는 배포판 차이가 아니라 패키지 미설치인 경우가 대부분이다(A.1.13).

A.1.15 책 전체가 쓰는 명령과 타입 이름을 대조했다 — 실측

A.1.14는 이 부록의 동사 목록을 실물과 맞췄다. 이번에는 대상이 다르다 — 133개 장이 실제로 적어 놓은 명령줄과 인터페이스 이름 전부다(실행 확인 — Jazzy · ros:jazzy-ros-base + ros2controlcli·rosbag2·sros2·nav2_msgs·moveit_msgs).

A.1.15.1 무엇을 어떻게 추출했나

A.1.15.2 결과 — 이름은 전부 맞았다

남은 10종은 책이 일부러 지어낸 예시 이름이다(my_interfaces/msg/MotorState·my_msgs/srv/SetMode·fleet_msgs/msg/Status 등). nav2_msgs·moveit_msgs처럼 ros-base에 없어 처음엔 "없음"으로 나온 9종은 패키지를 설치해 전부 확인했다 — 이름 오류와 미설치를 가르지 않으면 오판한다.

자동 대조의 오탐도 적어 둔다. 두 건이 "플래그 없음"으로 걸렸는데 둘 다 추출기의 잘못이었다: colcon test-result --verbose를 colcon test + --verbose로 잘라 읽었고, 0.7의 표 한 칸(` ros2 daemon stop, --no-daemon `)을 한 줄 명령으로 읽었다. 줄 단위 정규식은 산문과 표를 구별하지 못한다.

A.1.15.3 하나 걸린 것 — --ros-args는 ros2 run --help에 없다

$ ros2 run --help | grep -- --ros-args
(아무것도 안 나온다)

--ros-args는 ros2 run이 해석하지 않고 노드에 그대로 넘기는 인자이기 때문이다(1.1.5). 즉 없는 것이 정상이지만, "--help가 정본"(A.1.1)이라는 이 부록의 원칙을 그대로 적용하면 --ros-args는 존재하지 않는 옵션처럼 보인다.

--help가 정본이라는 원칙에는 예외가 하나 있다 — 노드에 전달되는 인자(--ros-args 이하 전부: -r·-p·--params-file·--log-level·--enclave)는 실행기(ros2 run·ros2 launch)의 도움말이 아니라 rcl의 인자 규약이다. 정본은 ros2 run <pkg> <exe> --ros-args --help(노드 자신이 답한다)이며, 이 책은 1.1.5·1.9.7·A.2에 그 목록을 두었다.

A.1.15.4 이 결과를 어떻게 읽을 것인가

이름은 틀리지 않았다. 그런데 82~90차에는 의미와 서명에서 결함이 꾸준히 나왔다 — 인자 개수(1.10.11), 폐기 오버로드(2.4), 체이닝 가능 여부(2.10.11.2), 우선순위 방향(4.6.11), 보고값과 동작의 불일치(1.6.12).

이 대비가 이 절의 결론이다. "그 이름이 있는가"는 문서를 보고 적어도 잘 맞는다 — 이름은 문서의 가장 눈에 띄는 부분이기 때문이다. 반면 "인자가 몇 개인가", "무엇이 먼저 우선하는가", "보고값이 동작과 같은가"는 문서에 없거나 한 줄로만 있어 옮겨 적는 과정에서 사라진다. 확인 노력은 이름이 아니라 의미 쪽에 쓰는 것이 옳다.

A.1.13 명령이 없거나 다를 때

ros2 --help·ros2 <명령> --help·ros2 <명령> <동사> --help 세 단계로 좁혀 가면 대부분 답이 나온다.