Metadata-Version: 2.4
Name: rainbow-rb-sdk
Version: 0.0.9.dev11
Summary: Rainbow Robotics 통합 Python SDK — AMR, 매니퓰레이터, RB-Y1 휴머노이드와 Rainbow Robot Service(common) 연동
Author-email: Derek <dfd1123@rainbow-robotics.com>
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
Requires-Dist: rainbow-rb-utils==0.0.9.dev11
Requires-Dist: rainbow-rb-zenoh==0.0.9.dev11
Requires-Dist: rainbow-rb-flat-buffers==0.0.9.dev11
Requires-Dist: rainbow-rb-schemas==0.0.9.dev11
Requires-Dist: rainbow-rb-log==0.0.9.dev11
Requires-Dist: rby1-sdk>=0.9.1

# rb_sdk

Rainbow Robotics 통합 Python SDK. AMR · Manipulator · RB-Y1 휴머노이드 제어와 Rainbow Robot Service(common) 연동을 단일 API로 제공합니다.

## 진입점

| 클래스 | 용도 |
|---|---|
| `RBAmrSDK` | AMR(자율 주행) 로봇 제어 |
| `RBManipulateSDK` | 협동 로봇 매니퓰레이터 제어 |
| `RBRby1SDK` | RB-Y1 휴머노이드 제어 |
| `RBBaseSDK` | 공통 베이스 (직접 상속하지 않는 한 사용할 일 없음) |

내부적으로 Zenoh pub/sub/query 메시 위에서 동작하며, 같은 PC(로봇 본체)에서 실행할 때는 별도 설정 없이 즉시 사용 가능합니다.

---

## 1. 설치

```bash
pip install rb_sdk
# RB-Y1 휴머노이드 제어가 필요하면 함께 설치
pip install rby1-sdk
```

`requires-python = ">=3.12,<3.13"` — Python 3.12 전용.

---

## 2. 기본 사용 (로봇 본체에서 실행하는 경우)

`common` 서비스와 같은 PC에서 실행되는 스크립트라면 추가 설정 없이 그대로 사용 가능합니다.

```python
from rainbow.rb_sdk import RBAmrSDK, RBManipulateSDK

amr = RBAmrSDK()
manipulate = RBManipulateSDK()

# 이 시점에 ZenohClient가 127.0.0.1:7447(common)에 자동 연결
manipulate.move.call_move_j(
    robot_model="C500920",
    target={"tar_values": [0, 0, 0, 0, 0, 0], "tar_frame": 0, "tar_unit": 0},
)
```

---

## 3. 외부 PC에서 사용 (Remote Connect)

개발용 노트북 등 **로봇 본체와 다른 머신**에서 로봇과 통신하고 싶다면 `sdk.connect()`를 호출합니다.

```python
import asyncio
from rainbow.rb_sdk import RBManipulateSDK

async def main():
    sdk = RBManipulateSDK()

    # 로봇(common 서비스)에 외부 peer로 등록 + 자동 heartbeat 시작
    peer_id = await sdk.connect(
        token="외부 서비스 Token",     # Muscat이 생성한 서비스 Token
        host="192.168.1.100",       # 로봇 IP
        ttl=30,                     # 서버 측 세션 TTL(초). heartbeat 끊기면 자동 해제
        # zenoh_port=None,          # None → OS가 빈 포트 자동 배정 (충돌 없음)
        # heartbeat_interval=15.0,  # 기본: ttl / 2
    )

    # ... SDK 호출 ...
    sdk.move.call_move_j(robot_model="C500920", target={...})

    await sdk.disconnect()

asyncio.run(main())
```

#### 주요 특징

- **로컬 IP 자동 감지**: `host` 방향의 라우팅 인터페이스 IP를 자동으로 찾아 로봇에 알림
- **포트 자동 배정**: 별도 지정 없이 OS가 빈 포트를 잡아주므로 포트 충돌 없음
- **자동 heartbeat**: 주기적으로 TTL 연장. 스크립트 종료 / 크래시 시 TTL 만료로 서버 측 정리
- **같은 PC 자동 감지**: `host`가 localhost거나 자기 IP인 경우 `connect()`는 아무것도 하지 않고 `None` 반환 (이미 메시 안에 있음)

#### connect() 인자

| 인자 | 타입 | 기본 | 설명 |
|---|---|---|---|
| `token` | `str` | (필수) | common 서비스 JWT |
| `host` | `str` | (필수) | common이 실행 중인 로봇 IP |
| `zenoh_port` | `int \| None` | `None` | 로컬 Zenoh listen 포트. `None`이면 자동 |
| `ttl` | `int` | `30` | 서버 측 세션 TTL(초) |
| `heartbeat_interval` | `float \| None` | `None` | heartbeat 주기. `None`이면 `ttl/2` |
| `mesh_timeout` | `float \| None` | `None` | mesh 형성 대기 최대 시간(초). `None`이면 무제한 대기 |
| `mesh_probe_timeout` | `float` | `1.0` | probe query 1회 timeout(초) |
| `mesh_probe_interval` | `float` | `0.5` | probe 재시도 간격(초) |

---

## 4. AMR SDK (`RBAmrSDK`)

```python
from rainbow.rb_sdk import RBAmrSDK

sdk = RBAmrSDK()
```

| 하위 모듈 | 기능 |
|---|---|
| `move` | 이동 명령(`move_to`, `move_jog` 등) |
| `control` | 전원/긴급정지/잠금 등 |
| `localization` | 위치 추정 |
| `map` | 맵 로드/저장 |
| `setting` | 환경설정 |
| `file` | 맵/리소스 파일 관리 |
| `status` | 상태 조회 |

---

## 5. Manipulate SDK (`RBManipulateSDK`)

```python
from rainbow.rb_sdk import RBManipulateSDK

sdk = RBManipulateSDK()
```

| 하위 모듈 | 기능 |
|---|---|
| `program` | 프로그램 실행/제어 |
| `move` | `call_move_j`, `call_move_l`, `call_move_jb_*` 등 |
| `config` | 환경설정/파라미터 |
| `io` | DIO/AIO 제어 |
| `get_data` | 상태·좌표 조회 |
| `point` | 포인트/좌표 등록 |
| `service` | 미니 탭 기능 |
| `maintenance` | 관리자 설정 |
| `state` | 실시간 상태 구독 |

---

## 6. RB-Y1 SDK (`RBRby1SDK`)

공식 `rby1-sdk` 래퍼.

```python
from rainbow.rb_sdk import RBRby1SDK

sdk = RBRby1SDK(endpoint="192.168.30.1:50051", model=None, auto_connect=True)

print(sdk.connected)
print(sdk.whoami())

sdk.control.power_on()
sdk.control.servo_on()

state = sdk.state.get_state()
print(state)

```

지원 메서드:

- 공통: `connect()`, `disconnect()`, `whoami()`, `call(method, *args, **kwargs)`
- 제어: `control.invoke(...)`, `control.power_on()`, `control.servo_on()`
- 상태: `state.get_state()`


---

## 7. 주의사항

- `RBBaseSDK`는 프로세스 단위 싱글톤 + 공유 ZenohClient 구조입니다. 같은 프로세스에서 여러 번 `RBManipulateSDK()`를 호출해도 동일 인스턴스가 반환됩니다.
- `RBRby1SDK`는 최초 `endpoint/model` 기준으로 세션이 공유됩니다.
- 연결 대상(zenoh, rby1 endpoint, Muscat HTTP)이 준비되지 않으면 런타임 예외가 발생합니다.
- 외부 PC에서 SDK 사용 시 **방화벽이 7447/TCP(zenoh)와 8000/TCP을 양방향으로 허용**해야 합니다.

---

## 8. 라이선스 / 문의

© Rainbow Robotics. 내부 이슈/문의: [GitHub Issues](https://github.com/rainbow-mobile/rainbow-release-apps/issues)
