제로웍스 로봇서비스 개발 가이드
제로웍스 로봇이 비스캣 관제(코어)와 결합하기 위한 개발 가이드입니다.
비스캣이 정의한 FMS 경쟁 모델을 기준으로, 로봇 펌웨어가 구현·연동해야 할 인증·미션·메시징 규약을 제공합니다.
- 대상 제로웍스 (로봇 벤더)
- 제공 주체 비스캣 (로봇 관제 코어 + API)
- 기준 일자 2026-05-27 작성 (2026-05-22 4사 협의 반영)
- 1차 결합 1.5차 PoC (2026-07) — 배송 1대 + 쓰레기 수거 1대, 룰 베이스
- 구성 개발 시나리오 · 연동 API 문서
이 가이드 구성
아래 두 문서로 나뉩니다. 먼저 시나리오로 전체 흐름을 잡고, API 문서에서 채널·페이로드를 확인하세요.
- 개발 시나리오 — 로봇 등록·인증부터 배송·쓰레기 수거 미션 한 사이클까지의 동작 흐름과 시퀀스.
- 연동 API 문서 — REST(FMS·인증), SQS 인바운드, IoT Core MQTT 아웃바운드 채널의 엔드포인트·페이로드·인증 규약.
1. 결합 개요
주문은 아이파크홈 앱 → 오토메타 커머스 백엔드 → 비스캣 코어 경로로 진입하고, 코어가 미션을 생성해 대기 큐에 적재합니다. 로봇은 코어에 직접 연결되지 않고 FMS 폴링으로 미션을 가져가 점유합니다. 단지 인프라(엘리베이터·로비폰) 제어는 코어가 단지서버 inBase를 경유해 처리하므로, 로봇은 단지 인프라를 직접 호출하지 않습니다.
- 미션 분배: FMS 경쟁 모델(REST Pull).
anyone 타입 — 후보 로봇 다수에게 동일 미션을 동시 제시하고, 먼저 executionTime=0을 보고한 로봇이 점유.
- 인증: 사전 등록된 robotId로 비밀키 1회 발급 → 모든 REST 요청에 HMAC-SHA256 서명 헤더(
X-Robot-Signature) 부착. X.509 인증서 병행.
- 메시징: REST(FMS 폴링·인증), AWS SQS(로봇 → 코어 이벤트 수신), AWS IoT Core MQTT(코어 → 로봇 응답·지시).
2. 로봇(제로웍스)이 구현할 책임
| 구분 | 책임 | 채널 |
|---|
| 인증 | 비밀키·인증서 발급 수신, 매 요청 HMAC 서명·timestamp 부착 | REST |
| FMS 폴링 | 주기적 상태 보고(요청 모드)와 미션 수신, 수행 가능 시 executionTime 보고(응답 모드)로 점유 시도 | REST |
| 주행·도착 | 경로 주행, 매장·세대 도착 이벤트 보고, 상태/배터리/위치 보고 | SQS |
| PIN 검증 | 점주(KDS)·사용자(박스 외부 키패드) 입력 PIN을 코어에 검증 요청, 결과 수신 후 해당 칸 개방 | SQS → MQTT |
| 4칸 적재함 | 코어가 주문 수량 기반으로 지시한 칸을 열고/잠금 (칸 선택은 코어가 결정, 점주 임의 선택 불가) | MQTT |
| 비대면 상차 감지 | 점주 상차 후 박스 닫힘을 감지해 이벤트 보고 → 이것이 배달 출발 트리거 | SQS |
3. 선결 조건·협의 항목
아래는 1.5차 결합 전 제로웍스와 확정해야 할 항목입니다. 확정 시 연동 API 문서의 해당 페이로드를 잠급니다.
- PIN 입력 채널 — 1.5차 로봇은 디스플레이가 없으므로 점주는 KDS, 사용자는 박스 외부 키패드로 입력. 로봇이 코어에 검증 요청하는 경로·페이로드 합의.
- 박스 닫힘 감지 센서·이벤트 페이로드 형식 (제로웍스 펌웨어).
- FMS 프로토콜 수용 범위 — 제로웍스 로봇 펌웨어가 폴링·점유·점유 보고를 어디까지 수용 가능한지(펌웨어 수정 범위·일정).
- 인증서 발급·저장 방식 (TPM 활용 여부), 네트워크 환경(VPN / 공용망 / 게이트웨이).
- 벤더별 어댑터 분리 지점 — 향후 청소 로봇 등 확장 시 어댑터 추가 경계.