CLI 완전정복 — ROS 2 시스템을 관측하고 진단하는 명령어

1. 문법이 하나뿐이다

ROS 2의 CLI는 외울 것이 많아 보이지만, 사실 구조가 하나입니다.

ros2 <목적어> <동사> [대상] [옵션]

목적어는 node, topic, service, action, param, interface, bag, pkg, launch, run, lifecycle, doctor, daemon 정도입니다. 동사는 대개 list, info, show, echo, call, set, get입니다.

이 구조를 알면 모르는 명령도 추측해서 찾을 수 있습니다. "액션 목록이 보고 싶다"면 ros2 action list일 것이고, 실제로 맞습니다.

막히면 --help를 붙이세요. 어느 단계에서든 붙습니다. ros2 --help, ros2 topic --help, ros2 topic echo --help 모두 동작합니다. 검색보다 이게 빠를 때가 많습니다.

탭 자동완성을 켜 두세요. 목적어와 동사는 물론 토픽 이름과 메시지 타입까지 완성됩니다. /robot1/scan 같은 긴 이름을 매번 치는 것과 탭 한 번의 차이는 큽니다.

용어 하나: 많은 Graph 조회 명령은 ROS 2 Daemon이 유지하는 Discovery 정보를 활용합니다. CLI Environment를 바꿨거나 Daemon 상태가 의심될 때 ros2 daemon stop 후 다시 조회할 수 있습니다. 그러나 Node가 안 보이는 원인은 Domain ID, Discovery Range, RMW, Network와 Security일 수도 있으므로 Daemon 재시작을 만능 해결책으로 보지 않습니다.

CLI 진단의 다섯 층

용도별로 묶어 두면 외울 것이 크게 줄어듭니다.

2. 무엇이 있는가 — 여섯 가지 목록 명령

문제를 만나면 먼저 무엇이 존재하는지부터 확인합니다. 상상하지 말고 눈으로 보세요.

ros2 node list — 살아 있는 노드. -a를 붙이면 숨겨진 노드까지 보입니다. 같은 이름의 노드가 두 번 보이면 중복 실행입니다. 이것만으로 해결되는 문제가 많습니다.

ros2 topic list -t — 토픽과 그 타입. -t를 붙이는 습관을 들이세요. 이름만 봐서는 타입 불일치를 못 잡습니다.

ros2 service list — 서비스. 노드마다 파라미터 서비스가 자동으로 붙으므로 grep -v parameter로 걸러 보면 편합니다.

ros2 action list -t — 액션.

ros2 param list — 조정 가능한 값 전부. 남의 노드를 처음 만났을 때 무엇을 바꿔 볼 수 있는지가 여기 다 나옵니다.

ros2 interface show <타입> — 메시지의 속. ros2 interface proto는 CLI로 채워 넣을 뼈대를 만들어 줍니다.

그리고 두 개를 더 ros2 node info /이름은 한 노드의 입출력을 통째로 보여 줍니다. 앞 화면에서 말했듯 소스를 열지 않고 역할을 파악하는 가장 빠른 방법입니다.

rqt_graph는 전체 그림을 한눈에 보여 줍니다. 노드가 열 개를 넘어가면 텍스트 목록보다 이쪽이 훨씬 낫습니다. 연결이 끊긴 노드가 외따로 떠 있는 것을 그림으로 보면 바로 알 수 있습니다.

존재를 확인하는 명령들. Daemon 재시작은 환경과 Discovery 조건을 확인하는 진단 단계 중 하나입니다.

# ── 무엇이 존재하는가 ───────────────────────────────────
ros2 node list                    # 살아 있는 노드
ros2 node list -a                 # 숨겨진 노드까지
ros2 node info /safe_driver       # 한 노드의 입출력 전부

ros2 topic list -t                # 토픽 + 타입 (항상 -t 를 붙이자)
ros2 topic list --include-hidden-topics

ros2 service list -t
ros2 service list | grep -v parameter   # 내 서비스만 보기

ros2 action list -t

ros2 param list                   # 모든 노드의 조정 가능한 값
ros2 param list /safe_driver


# ── 타입의 속을 보기 ────────────────────────────────────
ros2 interface show sensor_msgs/msg/LaserScan
ros2 interface proto geometry_msgs/msg/Twist             # 채워 넣을 뼈대
ros2 interface list | grep -i battery
ros2 interface package sensor_msgs


# ── 누가 이 타입을 쓰는가 ───────────────────────────────
ros2 topic find sensor_msgs/msg/LaserScan
ros2 service find std_srvs/srv/Trigger


# ── 전체 그림 ───────────────────────────────────────────
rqt_graph
# 노드가 열 개를 넘으면 텍스트 목록보다 훨씬 낫다.


# ── 목록에 없는데 노드는 떠 있다면 ──────────────────────
ros2 daemon status
ros2 daemon stop        # 다음 Graph 조회에서 Daemon이 다시 시작될 수 있다.
ros2 node list

주의 Daemon을 재시작해도 Domain ID, Discovery 범위, RMW와 Network 설정은 바뀌지 않습니다. Daemon 상태와 Environment를 확인한 뒤 같은 조건에서 최소 Talker·Listener로 문제를 분리하세요.

3. 어떻게 흐르는가 — 수치로 확인하기

존재를 확인했다면 다음은 흐름입니다. 여기서 중요한 것은 "느낌"이 아니라 "숫자"로 말하는 습관입니다.

ros2 topic echo /토픽 — 내용을 눈으로 봅니다. 그대로 쓰면 화면이 쏟아지므로 옵션을 함께 씁니다. • --once — 한 건만 보고 끝냅니다. 가장 자주 씁니다 • --field ranges — 특정 필드만 봅니다 • --no-arr — 큰 배열은 생략합니다. 라이다·이미지에 필수입니다 • --csv — 표 형태로 뽑아 다른 도구로 넘길 때

ros2 topic hz /토픽 — 실제 주파수. "20 Hz로 발행한다"는 코드의 주장이고, 이것은 사실입니다. 평균, 최소, 최대, 표준편차가 함께 나옵니다. 평균은 20인데 최대 간격이 300 ms라면 어딘가 밀리고 있다는 뜻입니다.

ros2 topic bw /토픽 — 실제 대역폭. 앞의 메시지 화면에서 계산으로 구한 값을 실측으로 확인하는 도구입니다. 무선이 느려질 때 어느 토픽이 범인인지 여기서 바로 나옵니다.

ros2 topic delay /토픽 — 발행 시각과 수신 시각의 차이. 주의: 메시지에 Header가 있어야만 동작합니다. Twist처럼 헤더가 없는 타입에는 쓸 수 없습니다. 이 값이 커진다면 처리 지연이나 시계 불일치를 의심합니다.

ros2 topic info /토픽 --verbose — 연결의 진실. 발행자 수, 구독자 수, 그리고 양쪽의 QoS 프로파일이 나옵니다. "연결이 안 된다"를 진단하는 가장 확실한 도구입니다. QoS 화면에서 배운 호환 규칙을 여기 출력에 대입하면 원인이 바로 보입니다.

hz의 최대 간격과 info --verbose의 QoS 프로파일이 실무에서 가장 자주 쓰는 두 가지입니다.

# ── 내용 보기 ───────────────────────────────────────────
ros2 topic echo /scan --once                  # 한 건만
ros2 topic echo /scan --no-arr                # 큰 배열 생략 (라이다·이미지 필수)
ros2 topic echo /scan --field ranges          # 특정 필드만
ros2 topic echo /odom --field pose.pose.position
ros2 topic echo /cmd_vel --csv                # 표 형태로 뽑기


# ── 주파수: 코드의 주장이 아니라 사실 ────────────────────
ros2 topic hz /scan
# average rate: 9.98
#   min: 0.089s max: 0.312s std dev: 0.0203s
#   -> 평균은 10 Hz 인데 최대 간격이 312 ms 다. 어딘가 밀리고 있다.

ros2 topic hz /scan --window 50               # 최근 50건 기준


# ── 대역폭: 무선이 느려질 때 범인 찾기 ───────────────────
ros2 topic bw /camera/image_raw
# 27.60 MB/s from 30 messages
#   -> 계산으로 구한 값과 실측이 맞는지 확인


# ── 지연: Header 가 있는 타입에서만 ─────────────────────
ros2 topic delay /scan
# Twist 처럼 Header 가 없는 타입에는 쓸 수 없다.


# ── 연결의 진실 (가장 중요한 진단 도구) ──────────────────
ros2 topic info /scan --verbose
# Publisher count: 1
#   QoS profile:
#     Reliability: BEST_EFFORT
#     Durability: VOLATILE
# Subscription count: 0        <- 구독자가 0 이다. 왜?
#
# 구독자가 RELIABLE 을 요구하고 발행자가 BEST_EFFORT 라면
# 앞 화면에서 배운 호환 규칙에 따라 연결되지 않는다.

4. 코드 없이 개입하기

CLI의 진짜 힘은 노드를 짜지 않고도 시스템에 개입할 수 있다는 점입니다. 가설을 세우고 30초 만에 검증할 수 있습니다.

ros2 topic pub — 토픽을 직접 발행합니다. Simulation이나 격리된 Test Topic에 직접 입력을 넣어 Upstream과 Downstream을 분리할 수 있습니다. 실제 /cmd_vel에 발행해 Robot이 움직였다고 해서 Hardware 전체가 정상이라고 단정할 수는 없지만 Command 경로 일부가 동작한다는 증거가 됩니다. 실제 구동은 Section 17의 안전 절차를 먼저 적용합니다. • -1 또는 --once — 한 번만 보냅니다 • -r 10 — 10 Hz로 계속 보냅니다. 주행 명령처럼 계속 와야 하는 것에 필수입니다

ros2 service call — 서비스를 호출합니다. 서버의 검증 로직을 시험하는 가장 빠른 방법입니다. 일부러 잘못된 값을 넣어 보세요.

ros2 action send_goal --feedback — 액션 목표를 보냅니다. 피드백이 Terminal에 표시됩니다. CLI Process 중단이 Goal Cancel과 동일하다고 가정하지 말고 Server 상태와 사용 중인 CLI 동작을 확인해 명시적인 Cancel·Safe Stop 절차를 준비합니다.

ros2 param set — 실행 중에 값을 바꿉니다. 노드를 재시작하지 않고 튜닝할 수 있습니다. 마음에 드는 조합이 나오면 ros2 param dump로 저장합니다.

ros2 run ... --ros-args — 실행할 때 배선을 바꿉니다. -r 리매핑, -p 파라미터, -r __ns:= 네임스페이스, --log-level을 조합하면 코드를 한 줄도 안 고치고 같은 노드를 다르게 띄울 수 있습니다.

안전 주의: ros2 topic pub /cmd_vel은 진짜로 로봇을 움직입니다. 실기에서 시험할 때는 바퀴를 띄우거나 주변을 비우고 하세요. 그리고 -r로 계속 보내다가 Ctrl+C를 누르면 명령이 끊길 뿐 정지 명령이 나가지 않으므로, 앞에서 배운 deadman timeout이 없다면 로봇은 마지막 속도로 계속 갑니다.

코드 없이 개입하는 다섯 가지. topic pub은 "하드웨어인가 소프트웨어인가"를 30초에 가릅니다.

# ── 토픽 직접 발행: 하드웨어인가 제어 노드인가 ───────────
# 한 번만
ros2 topic pub -1 /cmd_vel geometry_msgs/msg/Twist \
  "{linear: {x: 0.2}, angular: {z: 0.0}}"

# 계속 보내기 (주행 명령은 계속 와야 한다)
ros2 topic pub -r 10 /cmd_vel geometry_msgs/msg/Twist \
  "{linear: {x: 0.2}}"

# 정지
ros2 topic pub -1 /cmd_vel geometry_msgs/msg/Twist "{}"

# 무엇을 채워야 할지 모르겠다면
ros2 interface proto geometry_msgs/msg/Twist


# ── 서비스 호출: 검증 로직 시험 ──────────────────────────
ros2 service call /set_mode lab_interfaces/srv/SetMode \
  "{mode: 'auto', speed_limit: 0.8}"

# 일부러 틀린 값으로 서버의 방어를 시험한다
ros2 service call /set_mode lab_interfaces/srv/SetMode \
  "{mode: 'fly', speed_limit: 99.0}"


# ── 액션: 피드백까지 보면서 ─────────────────────────────
ros2 action send_goal --feedback /drive_distance \
  lab_interfaces/action/DriveDistance "{distance: 3.0, speed: 0.3}"
# 중단 시 Goal 상태와 Server의 Cancel 정책을 별도로 확인한다.


# ── 실행 중 파라미터 튜닝 ───────────────────────────────
ros2 param get /safe_driver stop_distance
ros2 param set /safe_driver stop_distance 0.6
ros2 param dump /safe_driver > config/tuned.yaml    # 마음에 들면 저장


# ── 코드를 고치지 않고 다르게 띄우기 ─────────────────────
ros2 run lab_nodes safe_driver --ros-args \
  -r __ns:=/robot2 \
  -r cmd_vel:=cmd_vel_raw \
  -p stop_distance:=0.6 \
  --log-level safe_driver:=DEBUG

주의 ros2 topic pub /cmd_vel은 실제로 로봇을 움직입니다. 실기에서는 바퀴를 띄우거나 주변을 비우세요. 또 -r로 계속 보내다 Ctrl+C를 누르면 명령이 끊길 뿐 정지 명령은 나가지 않습니다. deadman timeout이 없는 로봇은 마지막 속도로 계속 갑니다.

5. 결정 트리 — 무엇이 잘못됐는가

"안 된다"는 말은 정보가 아닙니다. CLI를 순서대로 써서 범위를 좁히세요. 아래 순서를 몸에 익히면 대부분의 문제가 몇 분 안에 잡힙니다.

① 노드가 살아 있는가 — ros2 node list 없다면: 실행이 실패했거나 다른 도메인입니다. 그 터미널의 출력을 봅니다. 중복으로 보인다면: 같은 노드를 두 번 띄운 것입니다.

② 토픽이 존재하는가 — ros2 topic list -t 없다면: 이름이 다릅니다. 네임스페이스나 리매핑을 확인합니다.

③ 데이터가 흐르는가 — ros2 topic hz 아무것도 안 나온다면: 발행자가 실제로 발행하지 않는 것입니다. 그 노드의 로그를 봅니다.

④ 연결되어 있는가 — ros2 topic info --verbose 구독자 수가 0이라면: 이름은 맞는데 QoS가 안 맞거나 구독자가 아직 안 뜬 것입니다.

⑤ 값이 이상한가 — ros2 topic echo --once 흐르기는 하는데 값이 이상하다면: 이제 알고리즘이나 센서의 문제입니다.

⑥ 설정이 맞는가 — ros2 param get "바꿨다고 생각하는 값"이 아니라 노드가 실제로 들고 있는 값을 봅니다.

⑦ 환경이 정상인가 — ros2 doctor, ros2 daemon stop 여기까지 와도 모르겠으면 환경 자체를 의심합니다.

이 순서가 좋은 이유: 각 단계가 다음 단계의 전제이기 때문입니다. 토픽이 없는데 QoS를 들여다보는 것은 시간 낭비입니다. 앞에서부터 순서대로 확인하면 헛수고가 없습니다.

기록해 두세요: 문제가 생긴 순간에 ros2 bag record -a -x "/camera.*"로 기록해 두면 나중에 천천히 분석할 수 있습니다. /rosout을 함께 담으면 로그까지 남습니다.

Topic 문제 진단 흐름

앞 단계가 통과해야 다음 단계가 의미를 가집니다. 순서를 지키면 헛수고가 없습니다.

6. 자주 쓰는 한 줄들

마지막으로 실무에서 손에 붙어 있는 한 줄들을 모았습니다. 외우려 하지 말고, 필요할 때 찾아 쓰다 보면 자연히 익습니다.

특히 아래 세 가지는 거의 매일 씁니다.

ros2 topic hz /토픽 — 주기가 정말 맞는지. ros2 topic info /토픽 --verbose — 연결과 QoS. ros2 daemon status — CLI Daemon 상태를 확인하고 필요할 때만 재시작합니다.

그리고 습관 하나: 새 시스템을 만나면 먼저 이 순서로 훑어보세요. ros2 node list → rqt_graph → 관심 있는 노드에 ros2 node info → ros2 param list. 5분이면 남이 만든 시스템의 구조를 파악할 수 있습니다.

rqt에 대해: rqt_graph 외에도 유용한 것이 많습니다. rqt_console(로그 필터), rqt_plot(값을 그래프로), rqt_reconfigure(파라미터를 슬라이더로). 터미널이 편하지만 값의 시간 변화를 볼 때는 rqt_plot이 압도적으로 낫습니다.

요점

• --help는 어느 단계에서든 붙는다. 검색보다 빠를 때가 많다.
• 탭 자동완성은 토픽 이름과 메시지 타입까지 완성해 준다.
• Graph Context와 Daemon 상태를 구분하고 필요할 때만 Daemon을 재시작한다.
• 값의 시간 변화는 터미널보다 rqt_plot이 압도적으로 낫다.
• 문제가 생긴 순간을 bag으로 남겨 두면 나중에 천천히 분석할 수 있다.

매일 쓰는 세 가지와 5분 훑기 순서. 새 시스템을 만났을 때 그대로 따라 하세요.

# ══ 매일 쓰는 세 가지 ═══════════════════════════════════
ros2 topic hz /scan                       # 주기가 정말 맞는가
ros2 topic info /scan --verbose           # 연결과 QoS
ros2 daemon status                        # 상태 확인 후 필요할 때만 stop


# ══ 새 시스템을 만났을 때 5분 훑기 ═══════════════════════
ros2 node list
rqt_graph
ros2 node info /관심노드
ros2 param list /관심노드


# ══ 자주 쓰는 조합 ══════════════════════════════════════
# 발행자가 하나도 없는 토픽 찾기
for t in $(ros2 topic list); do
  echo "$t : $(ros2 topic info $t | grep Publisher)"
done

# 특정 타입을 쓰는 토픽만
ros2 topic find sensor_msgs/msg/LaserScan

# 파라미터를 통째로 저장했다가 되돌리기
ros2 param dump /safe_driver > before.yaml
ros2 param set /safe_driver stop_distance 0.8
ros2 param load /safe_driver before.yaml   # 원상복구

# 큰 메시지를 배열 없이 훑기
ros2 topic echo /scan --no-arr --once

# 값의 시간 변화를 그래프로 (터미널보다 훨씬 낫다)
ros2 run rqt_plot rqt_plot /odom/twist/twist/linear/x

# 로그를 필터와 검색으로
ros2 run rqt_console rqt_console

# 파라미터를 슬라이더로 조정
ros2 run rqt_reconfigure rqt_reconfigure


# ══ 문제가 생긴 순간 남겨 두기 ═══════════════════════════
ros2 bag record -a -x "/camera.*" -o incident_$(date +%H%M%S)
# /rosout 도 함께 담기면 로그까지 남는다

7. CLI를 사용하기 전에 실행 Context를 고정한다

같은 명령도 Shell Environment가 다르면 전혀 다른 ROS Graph를 봅니다. 진단 Report 첫 부분에 다음 Context를 기록합니다.

echo "ROS_DISTRO=${ROS_DISTRO-<unset>}"
echo "ROS_DOMAIN_ID=${ROS_DOMAIN_ID-<unset>}"
echo "ROS_AUTOMATIC_DISCOVERY_RANGE=${ROS_AUTOMATIC_DISCOVERY_RANGE-<unset>}"
echo "ROS_LOCALHOST_ONLY=${ROS_LOCALHOST_ONLY-<unset>}"
echo "RMW_IMPLEMENTATION=${RMW_IMPLEMENTATION-<default>}"
echo "ROS_NAMESPACE=${ROS_NAMESPACE-<unset>}"

command -v ros2
ros2 doctor --report

이름은 절대 이름과 상대 이름을 구분한다

Node Namespace: /robot1
상대 Topic:     scan
완전한 이름:    /robot1/scan
절대 Topic:     /shared/map

CLI에서 /scan과 scan은 실행 Context에 따라 다른 이름이 될 수 있습니다. topic list, node info에서 실제 완전한 이름을 복사하고 Namespace·Remapping을 확인합니다.

# 같은 Executable을 다른 Namespace에서 실행
ros2 run demo_nodes_cpp talker --ros-args -r __ns:=/robot1

# Node 이름도 바꾸기
ros2 run demo_nodes_cpp talker --ros-args \
  -r __ns:=/robot1 -r __node:=status_talker

ros2 node list
ros2 node info /robot1/status_talker

같은 Node 이름을 여러 Process가 공유하면 Graph 조회와 Parameter Service 대상이 모호해질 수 있습니다. node list뿐 아니라 Process Manager와 Launch Log로 중복 실행을 확인합니다.

8. Package·Run·Launch 명령을 연결해 읽는다

# Package가 어느 Prefix에서 선택됐는가
ros2 pkg prefix lab_nodes

# Package가 제공하는 Executable
ros2 pkg executables lab_nodes

# 설치된 Package의 Share Directory
ros2 pkg prefix --share lab_bringup

# 직접 실행
ros2 run lab_nodes safe_driver --ros-args --log-level debug

# Launch File과 Argument 확인
ros2 launch lab_bringup robot.launch.py --show-args
ros2 launch lab_bringup robot.launch.py use_sim_time:=true

Package not found는 Package Discovery·Source 문제이고 No executable found는 Package는 보이지만 Entry Point 또는 CMake Install이 없다는 뜻입니다. ros2 pkg prefix와 pkg executables를 차례로 보면 두 문제를 빠르게 구분할 수 있습니다.

Launch 실행 전 --show-args로 Argument 이름과 기본값을 확인합니다. 실행 후에는 node list, node info와 Parameter 조회로 Launch 의도가 실제 Graph에 반영됐는지 검증합니다.

9. Service와 Action은 Type부터 확인한다

Service 진단 흐름

ros2 service list -t
ros2 service type /set_mode
ros2 interface show lab_interfaces/srv/SetMode
ros2 interface proto lab_interfaces/srv/SetMode

ros2 service call /set_mode lab_interfaces/srv/SetMode \
  "{mode: 'manual', speed_limit: 0.2}"

Service 이름이 보여도 Server가 Callback에서 오래 Blocking되면 응답이 늦을 수 있습니다. Terminal에서 호출 시간을 측정해 증거를 남깁니다.

time ros2 service call /set_mode lab_interfaces/srv/SetMode \
  "{mode: 'manual', speed_limit: 0.2}"

Action 진단 흐름

ros2 action list -t
ros2 action type /drive_distance
ros2 action info /drive_distance
ros2 interface show lab_interfaces/action/DriveDistance

ros2 action send_goal /drive_distance \
  lab_interfaces/action/DriveDistance \
  "{distance: 1.0, speed: 0.1}" \
  --feedback

Action은 Goal 수락, Feedback, Result와 Cancel이 분리됩니다. CLI Process를 중단했을 때 Server의 Goal이 어떤 상태가 되는지는 배포판·CLI와 Server 구현을 확인하고, 실제 Robot에서는 별도의 Cancel·Safe Stop 절차를 준비합니다.

10. Parameter는 현재값·설명·변경 결과를 함께 본다

ros2 param list /safe_driver
ros2 param describe /safe_driver stop_distance
ros2 param get /safe_driver stop_distance

ros2 param set /safe_driver stop_distance 0.6
ros2 param get /safe_driver stop_distance

ros2 param dump /safe_driver > safe_driver.yaml
ros2 param load /safe_driver safe_driver.yaml

param set이 성공했다는 것은 Node의 Parameter 변경 요청이 수락됐다는 뜻입니다. Algorithm이 Parameter를 생성 시 내부 변수에 한 번만 복사했다면 실제 동작은 바뀌지 않을 수 있습니다. 출력 Topic과 Log로 효과까지 검증합니다.

YAML을 Version Control에 저장할 때는 Node 이름과 Wildcard Scope를 확인합니다.

/safe_driver:
  ros__parameters:
    stop_distance: 0.6
    cruise_speed: 0.2

ros2 run lab_nodes safe_driver --ros-args \
  --params-file config/safe_driver.yaml

Secret, Token과 개인 식별정보를 Parameter Dump에 포함하지 않습니다.

11. Lifecycle Node의 상태와 전이를 확인한다

ros2 lifecycle nodes
ros2 lifecycle get /camera_driver
ros2 lifecycle list /camera_driver

# 허용된 전이를 확인한 뒤 요청
ros2 lifecycle set /camera_driver configure
ros2 lifecycle get /camera_driver
ros2 lifecycle set /camera_driver activate

Process가 node list에 보인다고 Application이 Ready인 것은 아닙니다. Lifecycle이 Active인지, Sensor Data와 Diagnostics가 정상인지 함께 확인합니다.

실제 Robot에서는 CLI로 순서를 무시한 전이를 임의 수행하지 않습니다. Hardware Resource, Command Output과 다른 Lifecycle Node의 Dependency를 Manager 정책에 맞춰 처리합니다.

12. TF는 Frame·시간·연결을 함께 진단한다

# 두 Frame 사이의 최신 Transform 관찰
ros2 run tf2_ros tf2_echo map base_link

# TF Tree PDF 생성
ros2 run tf2_tools view_frames

# Dynamic·Static TF Topic 확인
ros2 topic info /tf --verbose
ros2 topic info /tf_static --verbose
ros2 topic echo /tf_static --once --no-arr

TF 문제의 표준 순서:

1. Frame 이름 철자와 Prefix를 확인합니다.
2. Tree가 끊기지 않았는지 view_frames로 봅니다.
3. /tf_static의 Durability와 Late Joiner 수신을 확인합니다.
4. Header Stamp와 ROS Clock, use_sim_time을 확인합니다.
5. Buffer보다 과거·미래 Transform을 요청하는지 Error 전문을 봅니다.

ros2 param get /localizer use_sim_time
ros2 topic echo /clock --once
ros2 topic echo /scan --once --no-arr

tf2_echo가 기다린다는 사실만으로 Broadcaster가 없다고 단정할 수 없습니다. 시간 기준이 다르거나 Tree 중간 Edge가 빠져도 같은 증상이 나타납니다.

13. rosbag2 CLI로 현장 증거를 보존한다

# 기록 전 Topic·Type 확인
ros2 topic list -t

# 목적에 필요한 Topic만 기록
ros2 bag record -o incident_001 \
  /rosout /diagnostics /tf /tf_static /scan /odom /cmd_vel

# 무결성·개수 확인
ros2 bag info incident_001

# 실제 Robot Command를 안전 Namespace로 Remap해 재생
ros2 bag play incident_001 --ros-args \
  -r /cmd_vel:=/replay/cmd_vel

사용 중인 ROS 2 Distribution의 ros2 bag record --help와 play --help에서 Storage, Compression, QoS Override, Clock와 Topic Filter Option을 확인합니다. CLI Option은 rosbag2 Version에 따라 추가·변경될 수 있습니다.

전체 Topic 기록은 편하지만 Camera·PointCloud로 Disk와 CPU가 포화될 수 있습니다. 현장을 떠나기 전에 bag info에서 핵심 Topic Message 수와 Duration을 확인합니다.

14. Doctor·Daemon·Multicast로 환경 계층을 분리한다

ros2 doctor
ros2 doctor --report

ros2 daemon status
ros2 daemon stop
ros2 node list

# Middleware 이전 Multicast 연결 점검
ros2 multicast receive   # Computer A
ros2 multicast send      # Computer B

Node가 다른 Computer에서 안 보일 때

printenv | rg '^(ROS|RMW|CYCLONEDDS|FAST)'
ip -brief address
ip route
sudo ufw status verbose

확인 순서:

1. 두 Computer의 IP·Subnet·Route와 Wi-Fi Client Isolation
2. ROS_DOMAIN_ID
3. ROS_AUTOMATIC_DISCOVERY_RANGE 또는 구형 Discovery 설정
4. ROS_STATIC_PEERS와 DDS Vendor Configuration
5. RMW, Security Enclave와 Certificate
6. Firewall의 최소 허용 Rule

Daemon을 다시 띄워도 Network와 DDS 설정은 고쳐지지 않습니다. doctor --report에는 환경 경로와 Network 정보가 포함될 수 있으므로 외부 공유 전 민감정보를 검토합니다.

15. 측정 CLI의 숫자를 해석할 때 생기는 함정

topic hz, bw, delay는 CLI Subscriber가 실제로 받은 Sample을 기준으로 합니다. System 전체의 절대적 진실이 아니라 현재 CLI Endpoint의 관측값입니다.

QoS가 측정값에 미치는 영향

• CLI Subscription이 Publisher와 호환되지 않으면 Sample을 못 받습니다.
• Best Effort Wireless Link에서는 CLI 자체가 일부 Sample을 놓칠 수 있습니다.
• 큰 Message를 출력하면 Terminal Rendering이 측정에 영향을 줄 수 있습니다.
• 여러 Publisher가 같은 Topic에 있으면 합쳐진 Rate로 보일 수 있습니다.

ros2 topic info /scan --verbose
ros2 topic hz /scan --window 200
ros2 topic bw /scan

Delay와 Clock

Delay는 Message Stamp와 수신 Clock이 비교 가능해야 의미가 있습니다. 여러 Computer의 Clock이 동기화되지 않으면 Network 지연이 아니라 Clock Offset을 측정하게 됩니다. Simulation Time과 Wall Time을 섞어도 값이 왜곡됩니다.

date --iso-8601=ns
timedatectl status
ros2 param get /target_node use_sim_time

평균만 기록하지 말고 Window, 관측 시간, 최소·최대와 표준편차, QoS, Network 조건을 함께 남깁니다.

16. CLI 출력을 반복 가능한 진단 Report로 만든다

Command 출력은 Version에 따라 사람이 읽는 Format이 바뀔 수 있습니다. 자동화에서는 Tool이 제공하는 Structured Output Option이 있는지 --help로 확인하고, 안정된 API가 필요하면 rclpy·rclcpp 또는 rosbag2_py를 사용합니다.

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

report_dir="diagnostic_report"
mkdir -p "$report_dir"

date --iso-8601=seconds > "$report_dir/time.txt"
ros2 doctor --report > "$report_dir/doctor.txt" 2>&1 || true
ros2 node list > "$report_dir/nodes.txt" 2>&1 || true
ros2 topic list -t > "$report_dir/topics.txt" 2>&1 || true
ros2 service list -t > "$report_dir/services.txt" 2>&1 || true
ros2 action list -t > "$report_dir/actions.txt" 2>&1 || true

for name in ROS_DISTRO ROS_DOMAIN_ID ROS_AUTOMATIC_DISCOVERY_RANGE \
            ROS_LOCALHOST_ONLY RMW_IMPLEMENTATION; do
  printf '%s=%s\n' "$name" "${!name-<unset>}"
done > "$report_dir/ros_environment.txt"

이 Script는 Graph를 변경하지 않는 조회 명령만 사용합니다. Report를 외부로 보내기 전에 Host 이름, User 경로, 내부 IP, Device Serial과 Security 정보를 가립니다.

사람이 읽는 출력 Parsing의 한계

다음처럼 grep Publisher에 의존한 Script는 언어·Version·Format이 바뀌면 깨질 수 있습니다.

# 빠른 일회성 조사에는 쓸 수 있지만 장기 자동화 API로는 취약하다.
ros2 topic info /scan | rg 'Publisher count'

운영 Monitoring은 Diagnostics·Metric과 안정된 Program API를 사용하고 CLI Script는 설치 검증과 Incident Snapshot에 활용합니다.

17. 실제 Robot에서 CLI 개입을 안전하게 한다

조회 명령과 변경 명령을 구분합니다.

직접 구동 전 Checklist:

1. Robot을 Stand 또는 안전 구역에 놓고 구동 범위를 제한합니다.
2. Topic의 Publisher·Subscriber와 Mux 경로를 확인합니다.
3. Driver Watchdog와 E-stop을 시험합니다.
4. 속도·거리·시간을 최소값으로 시작합니다.
5. Terminal 중단과 Network 단절 뒤 실제로 정지하는지 확인합니다.
6. 시험 후 정지 명령, Mode와 Parameter를 원상복구합니다.

가능하면 실제 Command Topic 대신 Simulation이나 격리 Namespace를 사용합니다.

ros2 topic pub --once /test/cmd_vel geometry_msgs/msg/Twist \
  "{linear: {x: 0.05}, angular: {z: 0.0}}"

ros2 topic echo /test/cmd_vel --once

CLI는 Safety Controller가 아닙니다. Terminal이 멈추거나 Operator가 실수해도 Driver와 Hardware 계층이 독립적으로 안전 상태에 들어가야 합니다.

18. 확인 퀴즈 15문항

연습 문제

1. ros2 <목적어> <동사> [대상] [옵션] 구조를 예와 함께 설명하세요.
2. CLI 진단 전에 기록해야 할 ROS Environment와 Network Context를 쓰세요.
3. node list, node info, rqt_graph가 각각 보여 주는 범위를 비교하세요.
4. topic echo, hz, bw, delay, info --verbose가 답하는 질문을 설명하세요.
5. topic hz 결과가 System 전체의 절대 발행률이 아닐 수 있는 이유는 무엇인가요?
6. Service를 호출하기 전에 이름·Type·Interface를 확인하는 명령 순서를 쓰세요.
7. Action Goal의 수락·Feedback·Result·Cancel을 CLI에서 확인할 때 주의할 점은 무엇인가요?
8. Parameter 변경 명령이 성공해도 Robot 동작이 바뀌지 않을 수 있는 이유를 설명하세요.
9. Lifecycle Node가 node list에 보이는 것과 Application Ready의 차이를 설명하세요.
10. TF 문제를 Frame·Tree·QoS·Time 순서로 진단하는 명령을 쓰세요.
11. Bag 재생에서 실제 /cmd_vel 대신 안전 Namespace로 Remap해야 하는 이유를 설명하세요.
12. Daemon 재시작으로 해결할 수 있는 문제와 해결할 수 없는 문제를 구분하세요.
13. 다른 Computer의 Node가 보이지 않을 때 Network부터 DDS까지 확인 순서를 쓰세요.
14. CLI 출력을 장기 Monitoring Parser로 사용할 때 생기는 위험과 대안을 설명하세요.
15. 실제 Robot에 CLI로 Command를 발행하기 전·중·후 안전 절차를 작성하세요.

참고 자료

• ROS 2 command line tools
• Understanding ROS 2 nodes
• Understanding ROS 2 topics
• Understanding ROS 2 services
• Understanding ROS 2 actions
• Using parameters in a class
• ROS 2 QoS settings
• Using ros2doctor
• ros2cli API
• rosbag2 documentation