rainbow-rb-sdk 0.0.9.dev11

Rainbow Robotics 통합 Python SDK — AMR, 매니퓰레이터, RB-Y1 휴머노이드와 Rainbow Robot Service(common) 연동

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. 설치

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

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

---

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

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

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()를 호출합니다.

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)

from rainbow.rb_sdk import RBAmrSDK

sdk = RBAmrSDK()

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

---

5. Manipulate SDK (RBManipulateSDK)

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 래퍼.

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