ros_checker

ROS2 토픽/노드/서비스/액션을 그래프 전체 관점에서 모니터링하고, 항목을 역할별로 분류해 신호 상태와 통신 구조를 설명하는 CLI 앱입니다. Nav2 구동 가능성은 별도 nav2 커맨드에서만 검사하며, **LLM(ollama / Azure OpenAI)**으로 각 결과를 요약할 수 있습니다.

로컬(호스트 ROS2)과 Docker(컨테이너 ROS2) 환경 모두에서 동작합니다.

기능

커맨드	설명
ros-checker scan	ROS2 그래프를 카테고리별로 모니터링 — 센서/위치/제어/네비게이션 등의 역할과 통신 상태
ros-checker health	전체 토픽/노드/서비스/액션의 현재 상태와 이상 징후 모니터링
ros-checker nav2	Nav2 구동 가능성 체크 (라이프사이클, costmap, cmd_vel, 액션)
ros-checker doctor	실행 환경·DDS discovery·그래프 상태를 단계적으로 진단
ros-checker analyze	전체 모니터링 결과를 LLM으로 자연어 요약 (결과는 스타일 마크다운으로 출력)
ros-checker config	설정 출력 (config init/set으로 생성·수정)

모니터링 카테고리

토픽·서비스·액션은 이름과 통신 역할을 기준으로 다음 범주에 묶입니다.

• 센서: Lidar, 카메라, IMU, GPS 등 환경 인식 데이터
• 로컬라이제이션: 지도와 로봇 위치·자세 추정 데이터
• 오도메트리: 이동량 추정 데이터
• 네비게이션: 경로, costmap, 목표 지점 관련 통신
• 제어: cmd_vel, 관절·모터 제어 통신
• TF: 좌표 변환 통신
• 상태·진단: 배터리, 진단, 시스템 상태
• 시스템/기타: ROS2 내부 통신 및 미분류 항목

scan은 이 분류와 현재 발행자·구독자·주파수·대역폭을 보여주고, health는 전체 항목의 이상 징후를 요약합니다. Nav2 구동 여부는 nav2에서만 판단합니다.

문서

• AGENTS.md — 에이전트/개발자용 개발 가이드 (TDD, 스타일, 명령어)
• CONTRIBUTING.md — 기여 가이드
• SECURITY.md — 보안 취약점 보고 절차
• docs/PLAN.md — 초기 구현 계획

요구사항

• Python 3.12
• ROS2 (Jazzy 등) — rclpy 필요. source /opt/ros/<distro>/setup.bash 후 실행
• LLM: ollama(로컬) 또는 Azure OpenAI(클라우드)

설치 및 실행 (로컬)

uv sync --group dev
source /opt/ros/<distro>/setup.bash

# 그래프 모니터링 (카테고리별 출력)
uv run ros-checker scan

# 전체 통신 상태 모니터링
uv run ros-checker health

# Nav2 구동 가능성 (Nav2 전용)
uv run ros-checker nav2
uv run ros-checker doctor
uv run ros-checker doctor --deep

# LLM 종합 모니터링 진단
uv run ros-checker analyze

# 각 결과를 LLM으로 요약
uv run ros-checker scan --ai
uv run ros-checker health --ai
uv run ros-checker nav2 --ai

doctor는 기본적으로 환경과 DDS discovery를 빠르게 확인하며, --deep를 사용하면 토픽 측정과 Nav2 검사까지 수행합니다. 종료 코드는 정상 0, 경고 1, 오류 2이며, 자동화에서는 --json을 사용할 수 있습니다.

ROS2가 없는 환경에서도 --mock 플래그로 Mock 그래프를 사용해 기능을 확인할 수 있습니다. uv run ros-checker nav2 --mock 또는 uv run ros-checker health --mock

설정

설정은 플랫폼 표준 설정 디렉터리의 config.toml에서 읽습니다.

플랫폼	기본 경로
Linux	$XDG_CONFIG_HOME/ros-checker/config.toml (기본 ~/.config/ros-checker/config.toml)
macOS	~/Library/Application Support/ros-checker/config.toml
Windows	%APPDATA%\ros-checker\config.toml

config 커맨드로 관리합니다.

# 기본 config.toml 생성
ros-checker config init

# 항목 수정·저장 (점 표기 키)
ros-checker config set llm.provider azure
ros-checker config set llm.model gpt-4o
ros-checker config set llm.timeout 30

# 현재 유효 설정 출력
ros-checker config

설정 파일이나 .env가 없어도 내장 기본값으로 동작하므로, uvx 등에서 별도 파일 없이 바로 실행할 수 있습니다. 파일을 지정하려면 -c/--config와 --dotenv 플래그를 사용합니다.

LLM 설정

config init/config set으로 생성한 설정 파일이나 .env로 프로바이더를 선택합니다.

ollama (기본)

[llm]
provider = "ollama"
base_url = "http://localhost:11434"
model = "llama3.2"

Azure OpenAI

[llm]
provider = "azure"
base_url = "https://<resource>.openai.azure.com"
model = "<deployment-name>"
api_key = "<your-api-key>"

환경 변수로도 설정 가능합니다 (ROS_CHECKER_LLM__PROVIDER 등, .env.example 참고).

DDS/RMW 진단

scan과 health는 현재 프로세스의 RMW_IMPLEMENTATION, ROS_DOMAIN_ID, ROS_LOCALHOST_ONLY, discovery 범위를 함께 표시합니다. Cyclone DDS와 Fast DDS가 혼용되었다는 사실만으로 오류로 판정하지 않으며, 그래프가 비어 있거나 discovery가 실패한 경우에만 domain/network discovery/QoS 확인을 권고합니다.

원격 노드가 사용하는 RMW 구현은 표준 ROS2 그래프 정보만으로 확인할 수 없으므로, 체커는 원격 RMW를 추측하거나 혼용을 통신 불가의 원인으로 단정하지 않습니다.

uvx로 실행 (로봇에서)

패키지를 PyPI에 배포하면 로봇에서 uvx로 설치 없이 실행할 수 있습니다.

# ROS2 환경 source 후
source /opt/ros/<distro>/setup.bash

# 그래프 스캔 (rclpy 없으면 자동으로 ros2 CLI 사용)
uvx ros-checker scan

# CLI 소스 명시 (ros2 CLI만 필요, 가장 견고)
uvx ros-checker scan --source cli

# Nav2 체크 / LLM 진단
uvx ros-checker nav2 --source cli
uvx ros-checker analyze --source cli

동작 원리: uvx는 격리 환경을 만들지만 시스템 파이썬을 사용하므로 rclpy가 import 가능한 경우 rclpy 소스가 동작합니다. rclpy가 없거나 ~/.ros 로그 문제가 있으면 --source cli로 ros2 CLI만 사용해 동작합니다. 로봇에는 ros2 CLI가 항상 있으므로 --source cli가 가장 안정적입니다.

설정은 cwd가 아닌 플랫폼 기본 경로에서 읽으므로, 설정 파일이 없어도 기본값으로 동작합니다. 사용자 설정이 필요하면 uvx ros-checker config init로 기본 config를 만든 뒤 config set으로 수정하세요.

Docker 사용

체커는 ROS2 그래프의 노드로 참여하므로, ROS2 컨테이너와 **같은 네트워크 + 동일 ROS_DOMAIN_ID**로 실행해야 합니다.

docker compose build
docker compose up -d ros2-system   # ROS2 시스템(예: talker) 기동
docker compose run --rm checker scan
docker compose run --rm checker nav2
docker compose run --rm checker analyze

실제 Nav2/로봇 시스템을 사용한다면 docker-compose.yml의 ros2-system 서비스를 해당 이미지로 교체하세요.

개발

uv sync --group dev
uv run ruff check .
uv run ruff format --check .
uv run pytest

rclpy 통합 테스트는 ~/.ros에 로그를 쓰므로, 읽기 전용 환경에서는 ROS_LOG_DIR을 임시 경로로 지정하세요. 통합 테스트는 자체적으로 임시 디렉터리를 사용합니다.

아키텍처

┌─────────────────────────────────────────────────────┐
│  ros-checker CLI (wpycli 기반)                        │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐  │
│  │ Graph        │  │ Monitor      │  │ LLM       │  │
│  │ Introspection│→ │ Categories   │→ │ Analyzer  │  │
│  │ (rclpy/cli)  │  │ (rules)      │  │ (provider)│  │
│  └──────────────┘  └──────────────┘  └───────────┘  │
│        │                 │                │         │
│  ┌─────▼─────┐     ┌─────▼─────┐    ┌─────▼─────┐   │
│  │ ROS2 Graph│     │ Nav2      │    │ ollama /  │   │
│  │ (DDS)     │     │ Checker   │    │ AzureOpenAI│  │
│  └───────────┘     └───────────┘    └───────────┘   │
└─────────────────────────────────────────────────────┘

• src/ros_checker/cmds/ — CLI 커맨드 구현 (scan/health/nav2/analyze/config, 스피너 UX)
• src/ros_checker/graph/ — ROS2 그래프 인트로스펙션 (rclpy + ros2 CLI + Mock)
• src/ros_checker/analysis/ — 그래프 카테고리 분류 + 전체 모니터링 분석
• src/ros_checker/health/ — 일반 헬스 모델 + Nav2 전용 규칙
• src/ros_checker/llm/ — LLM 프로바이더 추상화 (ollama/Azure OpenAI)
• src/ros_checker/report/ — 테이블/JSON 리포트 및 마크다운 렌더링

라이선스

MIT 라이선스로 배포됩니다.