Metadata-Version: 2.5
Name: ros-dds-manager
Version: 0.1.0
Summary: ROS 2 DDS(CycloneDDS, Fast-DDS) XML 설정 생성 및 프로파일 전환 CLI
Project-URL: Homepage, https://github.com/wkqco33/ros-dds-manager
Project-URL: Repository, https://github.com/wkqco33/ros-dds-manager
Project-URL: Issues, https://github.com/wkqco33/ros-dds-manager/issues
Project-URL: Changelog, https://github.com/wkqco33/ros-dds-manager/blob/main/CHANGELOG.md
Author-email: wkqco33 <wkqco33@users.noreply.github.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: cli,cyclonedds,dds,fastdds,rmw,robotics,ros2
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Networking
Requires-Python: >=3.12
Requires-Dist: jinja2>=3.1.6
Requires-Dist: wpycli>=0.3.2
Requires-Dist: wpyconf
Requires-Dist: wpylog
Description-Content-Type: text/markdown

# ros-dds-manager (`rddm`)

[![PyPI version](https://img.shields.io/pypi/v/ros-dds-manager.svg)](https://pypi.org/project/ros-dds-manager/)
[![Python versions](https://img.shields.io/pypi/pyversions/ros-dds-manager.svg)](https://pypi.org/project/ros-dds-manager/)
[![License](https://img.shields.io/pypi/l/ros-dds-manager.svg)](https://github.com/wkqco33/ros-dds-manager/blob/main/LICENSE)
[![CI](https://github.com/wkqco33/ros-dds-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/wkqco33/ros-dds-manager/actions/workflows/ci.yml)

ROS 2 환경에서 DDS(CycloneDDS, Fast-DDS 등)의 복잡한 XML 설정 파일을 자동으로 생성하고, 상황에 맞추어 손쉽게 전환/적용할 수 있는 CLI 도구 및 Python 라이브러리입니다.

> **Tip**: 긴 명령어 대신 짧은 단축 별칭 **`rddm`**을 사용할 수 있습니다. (`ros-dds-manager`와 완전히 동일)
> ```bash
> rddm list
> rddm switch sim-local
> ```

---

## 📦 설치 (Installation)

PyPI에서 바로 설치합니다. Python 3.12 이상이 필요합니다.

```bash
# CLI 도구로 설치 (권장)
uv tool install ros-dds-manager
# 또는
pipx install ros-dds-manager

# 라이브러리로 사용
pip install ros-dds-manager
```

설치 후 `ros-dds-manager` 또는 `rddm` 명령을 사용할 수 있습니다.

```bash
ros-dds-manager --version
rddm doctor
```

<details>
<summary>소스에서 개발 환경 구성</summary>

```bash
git clone https://github.com/wkqco33/ros-dds-manager.git
cd ros-dds-manager
uv sync
uv run rddm --help
```

</details>

---

## 🚀 빠른 시작 (Quick Start)

### 1. 새 프로파일 생성
```bash
# 로컬호스트 격리 (공용 WiFi에서 토픽 충돌 방지)
uv run ros-dds-manager generate cyclonedds sim-local --localhost --domain-id 1 --activate

# 특정 유선 NIC 및 피어 지정 (Fast-DDS 멀티캐스트 비활성화)
uv run ros-dds-manager generate fastdds robot-eth --interface eth0 --no-multicast --peers 192.168.1.10,192.168.1.11

# 생성 미리보기 (Dry Run)
uv run ros-dds-manager generate cyclonedds preview-test --localhost --dry-run

# 대화형 마법사 실행 (TTY 전용)
uv run ros-dds-manager init
```

### 3. 프로파일 목록 및 상세 조회
```bash
uv run ros-dds-manager list
uv run ros-dds-manager list --json
uv run ros-dds-manager show sim-local
```

### 4. 프로파일 전환 (Switch)
```bash
# 활성 프로파일 교체
uv run ros-dds-manager switch sim-local
# 또는 별칭 사용
uv run ros-dds-manager use sim-local
```

### 5. 쉘 환경변수 연동 방법 (3가지 방식 지원)
CLI 도구(자식 프로세스)는 부모 쉘의 환경변수를 직접 바꿀 수 없으므로, 편의에 맞게 세 가지 방식 중 하나를 사용할 수 있습니다:

1. **`~/.bashrc` 영구 연동 (가장 추천)**:
   ```bash
   echo 'source ~/.config/ros-dds-manager/current.sh' >> ~/.bashrc
   ```
   `switch` 명령어로 활성 프로파일을 바꾸면 `current.sh`가 즉시 갱신되므로, 새 터미널마다 자동으로 선택된 DDS 환경이 적용됩니다.

2. **현재 쉘 즉시 적용 (one-shot)**:
   ```bash
   eval "$(ros-dds-manager env)"
   # 또는
   source ~/.config/ros-dds-manager/current.sh
   ```

3. **명령어 격리 실행 (`run`)**:
   현재 쉘 환경변수를 일체 건드리지 않고, 해당 프로파일이 적용된 서브프로세스로 실행합니다:
   ```bash
   ros-dds-manager run sim-local -- ros2 topic list
   ```

---

## 📋 주요 명령어 (Commands)

| 명령어 | 설명 | 예시 |
| :--- | :--- | :--- |
| `list` | 저장된 모든 DDS 프로파일 목록 및 활성 상태 표시 (`--json`, `--plain`) | `ros-dds-manager list --json` |
| `show [name]` | 프로파일 상세 정보, 생성된 XML, 환경변수 출력 (`--json`) | `ros-dds-manager show sim-local` |
| `switch <name>` | 활성 프로파일 변경 및 `current.sh` 갱신 | `ros-dds-manager switch robot-eth` |
| `env [name]` | 쉘 `export` 구문 출력 (`--unset` 지원) | `eval "$(ros-dds-manager env)"` |
| `generate` | 플래그 기반으로 XML 및 프로파일 생성 (`--dry-run`, `--overwrite`) | `ros-dds-manager generate cyclonedds my-prof --localhost` |
| `init [name]` | 대화형 마법사 질문-답변으로 프로파일 생성 (TTY 전용) | `ros-dds-manager init` |
| `delete <name>`| 프로파일 삭제 (`--yes` 지원) | `ros-dds-manager delete old-profile --yes` |
| `run <name> -- <cmd>` | 특정 프로파일 환경을 주입하여 명령 실행 | `ros-dds-manager run sim-local -- ros2 launch ...` |
| `doctor` | ROS 2 환경변수, 활성 XML, 네트워크 상태 진단 (`--json`) | `ros-dds-manager doctor` |
| `config` | 앱 설정(`config.toml`) 관리 (`init`, `show`, `path`, `set`, `get`) | `ros-dds-manager config show` |

---

## 🛡️ CLI 표준 준수 ([clig.dev](https://clig.dev/))

### 1. 표준 종료 코드 (Exit Codes)
| 코드 | 의미 | 설명 |
| :--- | :--- | :--- |
| `0` | `EXIT_SUCCESS` | 명령어가 성공적으로 완료됨 |
| `1` | `EXIT_ERROR` | 일반 런타임/운영 오류 (프로파일 없음 등) |
| `2` | `EXIT_USAGE` | 잘못된 플래그/인수 또는 비대화형 환경에서 필수 입력/확인(`--yes`) 누락 |
| `127`| `EXIT_NOT_FOUND` | `run` 명령에서 대상 실행 파일을 찾을 수 없음 |
| `130`| `EXIT_INTERRUPT` | 사용자가 Ctrl+C(SIGINT)로 인터럽트함 |

### 2. 표준 플래그
- `--json` / `-j`: 기계 판독이 용이한 JSON 형태로 출력 (CI/CD 및 파이프라인 연동)
- `--no-input`: 프롬프트 대기 없이 즉시 실패 (CI/에이전트 안전 장치)
- `-q`, `--quiet`: 팁과 상태 배너 출력을 억제하여 순수 결과만 표기
- `-y`, `--yes`: 파괴적 작업(`delete`) 시 확인 절차 스킵
- `--dry-run`: 실제 디스크 저장 없이 생성될 XML과 환경변수 미리보기

### 3. XDG Base Directory 규격 준수
설정 파일 및 프로파일 저장소는 다음 우선순위에 따라 결정됩니다:
1. `ROS_DDS_MANAGER_DIR` (사용자 지정 환경변수)
2. `$XDG_CONFIG_HOME/ros-dds-manager` (지정된 경우)
3. `~/.config/ros-dds-manager` (기본값)

---

## ⚙️ 설정 관리 (`config` 서브 커맨드)

`ros-dds-manager` 자체 동작 설정(`config.toml`)을 관리합니다:

- `ros-dds-manager config path`: 설정 파일 경로 및 존재 여부 확인 (`--local` 지원)
- `ros-dds-manager config show`: 현재 적용된 설정 내용 확인 (`--json` 지원)
- `ros-dds-manager config init`: 기본 `config.toml` 초기화 (`--overwrite`, `--local` 지원)
- `ros-dds-manager config set <key> <value>`: 설정값 변경 (예: `ros-dds-manager config set app.default_vendor fastdds`)
- `ros-dds-manager config get <key>`: 특정 키값 조회 (예: `ros-dds-manager config get app.default_vendor`)

---

## 💡 주요 시나리오별 설정 예제

### 시나리오 1: 연구실/카페 공용 WiFi에서 시뮬레이션 혼선 방지 (Localhost 전용)
```bash
ros-dds-manager generate cyclonedds local-gazebo \
    --localhost \
    --domain-id 1 \
    --activate
```

### 시나리오 2: 로봇 내부의 특정 이더넷 카드(`enp4s0`)로 통신 고정
```bash
ros-dds-manager generate cyclonedds robot-wired \
    --interface enp4s0 \
    --domain-id 42 \
    --buffer-mb 20 \
    --activate
```

### 시나리오 3: 멀티캐스트가 차단된 망에서 Fast-DDS 유니캐스트 피어 연결
```bash
ros-dds-manager generate fastdds office-unicast \
    --no-multicast \
    --peers 192.168.10.20,192.168.10.21 \
    --activate
```

### 시나리오 4: Fast-DDS Discovery Server 연결 (대규모 분산 로봇)
```bash
ros-dds-manager generate fastdds ds-client \
    --discovery-server client \
    --server-ip 192.168.1.100 \
    --server-port 11811 \
    --activate
```

---

## 🛠️ 개발 및 기여
- 에이전트 개발 지침: [AGENTS.md](file:///home/wkqco/Workspace/utils/ros-dds-manager/AGENTS.md)
- 변경 이력: [CHANGELOG.md](file:///home/wkqco/Workspace/utils/ros-dds-manager/CHANGELOG.md)
- 기여 가이드: [CONTRIBUTING.md](file:///home/wkqco/Workspace/utils/ros-dds-manager/CONTRIBUTING.md)
- 보안 정책: [SECURITY.md](file:///home/wkqco/Workspace/utils/ros-dds-manager/SECURITY.md)
- 라이선스: [LICENSE](file:///home/wkqco/Workspace/utils/ros-dds-manager/LICENSE) (Apache-2.0)
