로봇 API 통합 가이드: 로봇을 소프트웨어 스택에 연결

[← 가이드]

로봇 하드웨어를 기업 소프트웨어에 연결하는 엔지니어들을 위한 시스템 통합 가이드 API 설계, 실시간 통신 및 클라우드 연결 패턴을 다루는

통합 아키텍처 옵션

어떤 코드를 작성하기 전에, 요구 사항에 맞는 통합 패턴을 선택하십시오. 네 가지 주요 옵션은 각각 지연, 결합 및 생태계 호환성 사이의 다른 타협을 합니다.

Pattern	지연시간	Coupling	Best For
Direct SDK	<5ms	Tight — language/platform specific	Safety-critical control loops, high-frequency motion
REST API	50–200ms	Loose — language agnostic	Task dispatch, status queries, configuration
WebSocket	5–50ms	Medium — long-lived connection required	Real-time telemetry, servo commands, streaming
ROS2 bridge	10–100ms	Loose — uses ROS2 ecosystem	ROS2-compatible software, visualization, multi-robot

대부분의 생산 통합은 ** 조합**을 사용합니다: 작업 디스패치 및 상태 질의 (연연이 허용되는 경우) 를 위해 REST API, 실시간 텔레메트리 스트리밍을 위해 WebSocket, 그리고 로봇의 내장 컴퓨터에서 실행되는 낮은 수준의 제어 루프에 대한 직접 SDK. 네트워크에서 직접 SDK를 노출하지 마십시오. 이것은 모든 안전 추상화를 우회합니다.

로봇 제어에 필요한 REST API 설계

잘 설계된 로봇 REST API는 로봇을 자원과 작업으로 상위 수준의 객체로 취급합니다. 대부분의 사용 사례를 다루는 최소한의 API 표면은 다음과 같습니다.

POST /tasks 새로운 작업을 제출하세요. 몸: T1. 반환: T2.
GET /tasks/{id} 작업 상태를 얻으십시오. 현재 상태를 반환합니다 (열 / 실행 / 성공 / 실패), 실행 메트릭 및 실패 경우 오류 세부 사항.
GET /robots/{id}/status 로봇 건강을 얻으세요: 관절 온도, 배터리, 오류 코드, 현재 작업, 그리고 자세.
DELETE /tasks/{id} 줄을 서거나 실행 중인 작업을 취소합니다. 성공적으로 취소되면 200을 반환합니다.
** 인증:** 기계 간 통합을 위해 API 키를 사용 (소소유하고 감사 가능한) 또는 OAuth2 클라이언트 인증 흐름를 여러 임차 배치에 사용. 모든 요청에 T3 헤더에 키를 입력하십시오.
** 속도 제한:** API 게이트웨이 레이어에서 시행되는 ** 100 요청/초** 각 키 속도 제한을 적용하십시오. T4 헤더로 429 너무 많은 요청을 반환하십시오. 대부분의 통합은 이 제한에 접근하지 않습니다.

웹소켓 구현

웹소켓은 실시간 로봇 제어 및 텔레메트리 스트리밍에 필요한 쌍방향, 저 지연 채널을 제공합니다. 두 개의 별도의 웹소켓 채널이 권장됩니다. 명령에 대한 채널, 텔레메트리 에 대한 채널.

** 명령 스트림 (robot ← 클라이언트):** 클라이언트는 T5\ 형식 JSON 명령을 50100 Hz로 전송한다. 로봇의 내장 컨트롤러는 10 ms 이내에 각 명령을 인정하거나 안전한 정지 상태를 입력해야 한다. 명령 스트림에 JSON 대신 바이너리 코딩 (MessagePack 또는 CBOR) 을 사용한다.
** 텔레메트리 스트림 (로봇 → 클라이언트):** 로봇은 공동 상태, 최종 효과자 포지, 카메라 메타데이터 및 오류 코드를 10 Hz로 전송한다. 모니터링 및 시각화에는 10 Hz가 충분하다. 더 높은 속도에는 바이너리 코딩과 전용 네트워크 대역폭이 필요합니다.
** 심장 박동 및 재결합:** 클라이언트는 1초마다 핑 프레임을 보내야 한다. 로봇이 3초 동안 핑을 받지 않으면 안전 스톱 상태로 들어가게 된다. 일시적인 네트워크 중단을 처리하기 위해 클라이언트에서 기하급수적 백코프 재결합 논리를 구현한다 (제 1, 2, 4s, 8s에서 재결합한다).
** 메시지 순서:** 각 메시지에는 단조적으로 증가하는 순서 번호를 포함합니다. 수신자는 떨어진 메시지를 감지하고 다음 메시지를 간섭하거나 기다려야할지 결정할 수 있습니다.

ROS2 웹 브릿지

기존 ROS2 인프라를 가진 팀에서는 rosbridge_suite는 JSON 코딩으로 WebSocket에서 ROS2 주제, 서비스 및 작업을 노출합니다. 이것은 웹 패시보드와 ROS2 자체를 실행하지 않고 ROS2 그래프와 상호 작용할 수 있도록합니다.

rosbridge_server: T6를 통해 설치합니다. 기본으로 포트 9090에서 WebSocket 서버를 실행합니다. 클라이언트는 간단한 JSON 프로토콜을 사용하여 ROS2 주제에 연결하고 가입/포스트합니다.
roslibjs: 로즈브리지의 자바스크립트 클라이언트 라이브러리. 웹 패시보드에서 T7, T8 및 사용자 지정 주제에 가입하고 브라우저에서 ROS2 서비스를 호출할 수 있습니다.
JSON 코딩 오버헤드: rosbridge는 ROS2의 원산 CDR 바이너리 코딩보다 510x 더 큰 JSON 코딩을 사용합니다. 높은 주파수 주제를 (>10 Hz, 큰 메시지) 위해, 브리지 전에 전용 바이너리 브리지 또는 필터링 주제를 고려하십시오.
** 보안 참고:** 로즈브리지는 기본적으로 인증이 없습니다. [함대 관리 지침] (T20) 에서 설명한 와이어 가드 VPN 뒤에 항상 실행하십시오. 인터넷에 직접 노출되지 않습니다.

기업 통합 패턴

로봇을 기업 시스템 (WMS, ERP, MES) 에 연결하는 것은 항상 작동하는 기업 시스템과 때때로 오프라인 로봇 사이의 신뢰성 불균형을 처리하는 패턴이 필요합니다.

** 작업 배송을 위한 메시지 줄을 (Kafka 또는 RabbitMQ):** WMS는 카프카 주제에 대한 선택 명령을 게시합니다. 로봇 함대 관리자는 주제에서 소비하고 사용할 수 있는 로봇에게 작업을 배송합니다. 작업이 도착할 때 로봇이 오프라인에 있다면 작업은 로봇이 사용할 수 있을 때까지 줄을 잇습니다. 이것은 WMS를 로봇의 사용 가능성에 분리합니다.
** 주문 이벤트 에 대한 ERP/WMS 웹 :** 새로운 주문이 준비 된 때 WMS 는 로봇 플랫폼 API 에 웹 을 게시하도록 구성합니다. 로봇 플랫폼은 웹 을 처리하고 작업을 배포합니다. 가짜 주문 주입을 방지하기 위해 웹 서명 검증을 구현하십시오 (HMAC-SHA256).
** 시간 시리즈 텔레메트리 데이터베이스 (InfluxDB):** 장기 분석 및 컴플라이언스 보고를 위해 로봇 텔레메트리를 InfluxDB에 저장합니다.

보안 구현

** 모든 네트워크 통신에 대한 TLS 1.3:** 모든 REST, WebSocket 및 rosbridge 트래픽은 TLS 1.3을 사용해야 합니다. T9 및 HSTS 헤더로 리버스 프록시를 (Nginx 또는 Caddy) 구성하십시오. 클라우드 서비스에 연결되는 로봇은 서버 인증서를 검증해야 합니다.
** 로봇 클라이언트들을 위한 인증서 :** 로봇 탑재 소프트웨어 는 예상되는 서버 인증서 지문 을 고 예상치 못한 인증서와의 연결을 거부 해야 합니다. 이 방법은 허위 AP가 존재할 수 있는 공장/하우스 네트워크 환경에서 중간에 있는 인격 공격을 방지 합니다.
** 민감한 환경의 VPN:** 고 보안 환경 (약품, 국방, 금융) 의 배포를 위해, 모든 로봇 클라우드 통신을 WireGuard VPN 터널을 통해 라우팅하십시오. 로봇의 클라우드 연결은 여러 개인 보안 연결보다는 단일 인증된 암호화 터널입니다.
감독 로그: 각 API 호출을: 타임 스탬프, API 키 ID (키 자체), 엔드포인트, 응답 상태 및 요청 IP로 로그. 한 번 작성 저장 저장 (AWS CloudTrail 또는 GCP Cloud Audit Logs) 에 저장하십시오. 이것은 SOC 2 준수 및 사고 조사에 필요합니다.

시험 과 조롱

** 개발을 위한 가짜 로봇 서버:** 현실적인 시뮬레이션 데이터로 전체 로봇 API에 응답하는 가짜 HTTP/WebSocket 서버를 구축하십시오. 개발자는 물리적 로봇 접근이 필요없이 모크에 대한 통합을 구축하고 테스트 할 수 있습니다. 모크는 결정적 통합 테스트를 위해 녹화 된 로봇 세션들을 재생해야 합니다.
** 시뮬레이션 기반의 통합 테스트:** 전체 스택 (WMS → 로봇 플랫폼 → 로봇 → 텔레메트리 → 대시보드) 의 종합 테스트를 위해, 가제보 또는 아이작 시밍에서 시뮬레이션된 로봇을 사용하십시오. 이 테스트는 각 트러 요청에 따라 CI로 실행되며, 단위 테스트에서 놓친 캡치 통합 회귀를 수행합니다.
** 계약 테스트:** 로봇 API 제작자 (러봇 플랫폼) 와 API 소비자 (WMS 통합, 대시보드) 가 API 스키마에 동의하는지 확인하기 위해 Pakt 또는 유사한 계약 테스트 프레임워크를 사용하십시오. 이것은 통합이 될 때까지 변경 사항이 감지되지 않도록 방지합니다.

통합 아키텍처 다이아그램

생산 창고 배치에 대한 전형적인 엔드-투-엔드 아키텍처:

** 1층 로봇 하드웨어:** 로봇 팔 + ROS2를 실행하는 내장 컴퓨터, 500 Hz에서 SDK 직접 제어 루프, 지역 안전 감시견.
층 2 로봇 플랫폼 (현장 또는 클라우드): 작업 관리에 필요한 REST API, 실시간 텔레메트리용 WebSocket 서버, RCSV 플랫폼 함대 패시보드 및 정책 배포에 필요한
** 3층 기업 통합:** Kafka 메시지 버스는 WMS 주문 이벤트를 소비하고 로봇 플랫폼에 전송합니다.
4층 기업 시스템: WMS (하우스 관리), ERP (재산, 금융), MES (산업 실행 시스템) 모두 3층만 통신하고, 로봇과 직접 통신하지 않습니다.

OpenArm 1 ROS2 인터페이스: 구체적인 주제

OpenArm 1 는 다음 주제 구조를 가진 로스2 드라이버를 제공합니다. 이것은 위에서 설명한 패턴을 통해 모든 팔을 통합하는 참조 구현으로 사용됩니다.

T10 -- 센서_msgs/JointState 50 Hz. 7 필드: 6 관점 + 1 지갑 열. 상태 인터페이스: 위치, 속도, 노력.
T11 -- 궤도_msgs/JointTrajectory. 위치 모드 명령은 로스2_컨트롤을 통해 최대 50 Hz로
T12 -- 기하학_msgs/크리 100 Hz (F/T 센서가 연결될 때) 에 착된. 손목 플랜지에서 6축의 힘/토크.
T13 -- std_msgs/Float64. 프
T14 -- 진단_msgs/DiagnosticArray. 엔진 온도, 오류 코드, 펌웨어 버전. 1 Hz에서 출판되었습니다.
ROS2 서비스: T15 -- 위치, 속도, 그리고 막기 제어 모드 사이의 스위치.
ROS2 액션: T16 -- 목표 최종 효과자 포즈를 받아들이고 MoveIt2 계획 파이프라인을 통해 실행합니다.

파이썬 클라이언트 예제: REST API 통합

작업을 파견하고 완료를 모니터링하고 텔레메트리를 검색하는 최소한의 파이썬 클라이언트:

import requests, time

API_URL = "https://platform.roboticscenter.ai/api/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. Submit a task
task = requests.post(f"{API_URL}/tasks", json={
    "task_type": "pick_and_place",
    "robot_id": "arm-001",
    "parameters": {
        "pick_pose": [0.3, 0.1, 0.05, 0, 0, 0, 1],
        "place_pose": [0.3, -0.2, 0.05, 0, 0, 0, 1]
    },
    "priority": 1
}, headers=HEADERS).json()

task_id = task["task_id"]
print(f"Task submitted: {task_id}")

# 2. Poll for completion
while True:
    status = requests.get(
        f"{API_URL}/tasks/{task_id}", headers=HEADERS
    ).json()
    if status["status"] in ("succeeded", "failed"):
        break
    time.sleep(1.0)

print(f"Result: {status['status']}")

# 3. Get robot telemetry
health = requests.get(
    f"{API_URL}/robots/arm-001/status", headers=HEADERS
).json()
print(f"Joint temps: {health['joint_temperatures']}")
print(f"Battery: {health['battery_pct']}%")

오류 처리 및 재시험 전략

Idempotency: 모든 POST/tasks 요청에는 클라이언트 생성된 T17 (UUID) 를 포함해야 합니다. 서버는 동일한 키가 다시 제출되면 기존 작업을 반환하여 네트워크 재시험에서 복제 작업 생성을 방지합니다.
** 기하급수적 백오프로 재시행:** 5xx 서버 오류 및 네트워크 타임아웃에 대해, 최대 4 번의 재시행으로 1s, 2s, 4s, 8s 간격에서 재시행. 4xx 클라이언트 오류에 대해서는 재시행하지 마십시오. 요청을 수정하십시오.
WebSocket 재 연결: 텔레메트리 웹소켓이 연결을 끊으면 클라이언트는: (1) 1초를 기다려야 하고, (2) 다시 연결을 시도해야 하며, (3) 모든 주제에 다시 가입해야 하며, (4) REST 백필 엔드포인트 T18을 통해 누락된 텔레메트리의 마지막 10초를 요청해야 합니다.
** 회로 차단기 패턴:** 로봇이 5 개의 연속 API 호출에서 오류를 반환하면 60 초 동안 회로 차단기를 열십시오. 이 기간 동안, 모든 요청이 해당 로봇에 캐시 상태가 고갈됩니다. 60 초 후에 단일 건강 검사 요청을 보내십시오. 성공하면, 브레이커를 닫고 정상적인 작업을 재개하십시오.

RCSV와 작업

RCSV 플랫폼은 로봇 제어, 함대 관리 및 기업 통합을 위한 생산 수준의 API를 제공합니다.

데이터 플랫폼 - 작업 디스패치, 텔레메트리 및 함대 관리에 필요한 REST 및 WebSocket API
데이터 수집 서비스 -- API를 기반으로 데이터 수집과 프로그램 작업 제출 및 전달
하드웨어 스토어 -- OpenArm 1 선비용 ROS2 드라이버와 API 통합 패키지
우리와 연락하세요 -- 당신의 배포에 대한 통합 아키텍처 검토를 요청합니다

RCSV 플랫폼과 더 빠르게 통합

RCSV 플랫폼은 로봇 배포를 위해 미리 구축된 REST 및 WebSocket API, 함대 관리 및 기업 통합 연결을 제공합니다.

[플랫폼을 탐험]

OpenArm

Browse the Store

Data Marketplace

Get Started with Physical AI

Wuji Teleop Glove

Unitree Go2 — Setup & SDK