부록 부록

A.2 QoS·환경변수·설정 레퍼런스

A.2.1 이 부록의 사용법

QoS 정책과 환경 변수는 "알고 있으면 5분, 모르면 하루"인 종류의 지식이다. 이 부록은 그것을 한자리에 모은다.

정직: 환경 변수의 지원 여부·기본값·정확한 이름은 배포판과 RMW 구현에 따라 다르다(확인 필요). 특히 벤더별 설정은 해당 DDS 문서가 정본이다.

다만 이 부록은 이 책에서 실행 검증이 가장 많이 적용된 곳이다 — 내장 QoS 프로파일 전 필드, BEST_AVAILABLE, ROS_LOCALHOST_ONLY 폐기, 디스커버리 범위 값, ROS_LOG_DIR·ROS_STATIC_PEERS, 그리고 존재하지 않는 환경변수 3종이 실측으로 확인·정정됐다. 본문의 (실행 확인) 표기가 붙은 항목은 Jazzy 실물과 대조한 것이고, 표기가 없는 항목은 여전히 문서 기준이다(목차 3의 검증 범위 표).

A.2.2 QoS 정책 요약

모든 정책에 SYSTEM_DEFAULT(RMW/XML에 위임)와 UNKNOWN(조회 결과에만 등장)이 추가로 존재한다. BEST_AVAILABLE은 History에는 없다 — KEEP_LAST/KEEP_ALL뿐이다(실행 확인: rclpy HistoryPolicy 열거형). History는 호환성 판정 대상이 아니라 협상할 것이 없기 때문이다. 의미와 함정은 1.5.3.8.

A.2.3 호환성 매트릭스

발행자(offered)와 구독자(requested)가 호환되어야 연결된다(1.5.4).

Reliability:

Durability:

규칙: 발행자가 구독자의 요구 이상을 제공해야 한다.

연결이 안 될 때 첫 명령: ros2 topic info <topic> -v(A.1.3). 양쪽 QoS가 그대로 나온다.

A.2.4 표준 프로파일

표 전체를 Jazzy 헤더(rmw/qos_profiles.h·rcl/logging_rosout.h)와 대조해 확인했다(실행 확인).

// C++
auto qos = rclcpp::SensorDataQoS();
auto qos2 = rclcpp::QoS(rclcpp::KeepLast(1)).best_effort().durability_volatile();
auto latched = rclcpp::QoS(1).transient_local().reliable();   // 지도·정적 데이터

# Python
from rclpy.qos import qos_profile_sensor_data, QoSProfile, ReliabilityPolicy, DurabilityPolicy
qos = QoSProfile(depth=1, reliability=ReliabilityPolicy.BEST_EFFORT)
latched = QoSProfile(depth=1, durability=DurabilityPolicy.TRANSIENT_LOCAL)

A.2.5 용도별 권장 구성

함정: 가장 흔한 사고는 센서에 RELIABLE을 쓰는 것(1.6.3.1)과 /map을 VOLATILE로 구독하는 것(11.4.4)이다.

A.2.6 핵심 환경 변수

기본 로그 레벨을 바꾸는 환경변수는 Jazzy에 없다(실행 확인). RCUTILS_LOGGING_SEVERITY는 존재하지 않으며 설정해도 무시된다. 레벨은 --ros-args --log-level이나 /<노드>/set_logger_levels 서비스로 바꾼다(1.11.4).

| ROS_SECURITY_ENABLE | 보안 활성 | 13.2.6 | | ROS_SECURITY_STRATEGY | Enforce/Permissive | 13.2.6 | | ROS_SECURITY_KEYSTORE | 키스토어 경로 | 13.2.3 | | ROS_SECURITY_ENCLAVE_OVERRIDE | enclave 경로 자동 계산을 덮어쓴다 — 기본은 컨텍스트 이름으로 <키스토어>/enclaves/<경로>를 찾는다(실행 확인) | 13.2.12.4 | | FASTRTPS_DEFAULT_PROFILES_FILE | Fast DDS XML(확인 필요) | 3.7 | | CYCLONEDDS_URI | Cyclone DDS 설정(확인 필요) | 3.8 | | FASTDDS_LOG_LEVEL | Fast DDS 자체 로그 수준 — RMW 아래를 볼 때 | 3.7 | | AMENT_PREFIX_PATH | ament 검색 경로 | 4.1 | | CMAKE_PREFIX_PATH | CMake 패키지 검색 경로 — 오버레이가 쌓이는 실체(0.5.3) | 0.5·4.2 | | LD_LIBRARY_PATH | 공유 라이브러리 검색 경로 — 소싱이 빠지면 여기가 비어 노드가 기동되지 않는다 | 0.5·14.8.4 | | ROS_DISTRO | 현재 소싱된 배포판 이름(jazzy) — 스크립트에서 분기할 때 | 0.4·4.6 | | COLCON_* | colcon 동작 | 4.5 |

함정: ROS_DOMAIN_ID가 노드마다 다르면 서로를 못 본다(1.5.8) — "아무것도 안 보인다"의 최다 원인 중 하나. printenv | grep ROS로 모든 터미널에서 확인하라.

함정: RMW_IMPLEMENTATION이 노드마다 다르면 통신되지 않는다(3.5.6). systemd 서비스와 SSH 셸의 환경이 다를 수 있으므로(14.8.4) 양쪽을 확인한다.

A.2.7 설정 파일 체계

A.2.8 파라미터 YAML 형식

# 노드 이름·네임스페이스가 정확히 일치해야 적용된다 (1.7.9)
/my_node:
  ros__parameters:
    rate: 20.0
    frame_id: "base_link"
    thresholds: [0.1, 0.5, 1.0]
    nested:
      value: 3

# 네임스페이스가 있으면
/robot1/my_node:
  ros__parameters:
    rate: 20.0

# 와일드카드 (확인 필요: 정확한 동작 범위)
/**:
  ros__parameters:
    use_sim_time: true

적용 확인의 표준 절차: ros2 param dump /my_node로 실제 값을 본다(A.1.5).

A.2.9 자주 쓰는 로그 설정

# 실행 시 레벨
ros2 run my_pkg my_node --ros-args --log-level debug
ros2 run my_pkg my_node --ros-args --log-level my_node:=debug   # 노드별

# 형식 (확인 필요: 지시자)
export RCUTILS_CONSOLE_OUTPUT_FORMAT="[{severity}] [{time}] [{name}]: {message}"

# 파일 위치
ls ~/.ros/log/latest/                  # ★ 정기 정리 필요 (14.8.9)

고빈도 콜백에서는 RCLCPP_*_THROTTLE을 쓰라(1.11.5·12.6.8).

A.2.10 시간 관련 설정

# launch에서 전체 적용 (14.3.5)
SetParameter(name='use_sim_time', value=True)

A.2.11 성능 관련 설정 요약

성능 문제의 첫 확인은 빌드 타입이다(12.6.8). 디버그 빌드로 운영하는 경우가 의외로 흔하다.

A.2.12 빠른 진단 대응표