제로웍스 로봇서비스 개발 가이드

제로웍스 로봇이 비스캣 관제와 연동해야 할 인증·미션·메시징 규약을 제공합니다.

대상 제로웍스 (로봇)
제공 주체 비스캣 (로봇 관제 + API)
기준 일자 2026-05-27 작성 · 2026-06-04 미션 할당 MQTT 입찰·점유 모델로 개정 · 2026-06-11 s2r/r2s 토픽·3단계 입찰·goals 데이터 모델로 개정 · 2026-06-17 mode → goal → mission 3계층 데이터 모델로 개정(v3)
1차 결합 1.5차 PoC (2026-07) — 배송 1대 + 쓰레기 수거 1대, 룰 베이스
구성 개발 시나리오 · 연동 API 문서 · 로봇 발행 항목

이 가이드 구성

아래 세 문서로 나뉩니다. 먼저 시나리오로 전체 흐름을 잡고, API 문서에서 채널·페이로드를 확인하세요.

개발 시나리오 — 로봇 등록·인증부터 배송·쓰레기 수거 미션 한 사이클까지의 동작 흐름과 시퀀스. 배송 두 케이스(단건 / 주행 중 추가 묶음)의 메시지 레벨 통신 플로우 예시 포함(§8).
연동 API 문서 — REST(인증·맵 등록), MQTT(로봇↔관제 전 메시지: 상태·알람·미션·입찰·PIN·박스) 채널의 토픽·페이로드·인증 규약.
로봇 발행 항목 — 관제 운영에 필요한 추가 발행 데이터(상태 확장·접속 유지·보행자 안전·충전 도킹·미션 예외 사유·미션 수행 거리·소프트웨어 인벤토리)의 채널·페이로드 규약.

1. 연동 개요

주문은 오토메타 커머스 앱 → 오토메타 커머스 백엔드 → 비스캣 관제 경로로 진입하고, 관제가 미션을 생성해 대기 큐에 적재합니다. 로봇 서비스는 mode → goal → mission 3계층으로 정의하며, 한 mission(고객 오더 단위)은 여러 goal에 걸칠 수 있습니다(픽업 goal + 하차 goal). 관제가 수행 가능한 후보 로봇에게 MQTT로 미션을 제시(입찰 요청)하면 로봇들이 goal별 예상 도착시간을 입찰하고, 관제가 최소 도착시간 기준으로 배차를 결정해 통보합니다. 단지 인프라(엘리베이터·로비폰) 제어는 관제가 처리하므로, 로봇은 단지 인프라를 직접 호출하지 않습니다.

미션 분배: MQTT 3단계 입찰(offer → bid → result). 후보 로봇에게 goal 배열을 제시 → 각 로봇이 goal별 예상 도착시간 입찰 → 관제가 최소 도착시간(추후 적재공간 포함)으로 배차 결정. mission.atomic으로 한 미션 goal들의 순서 보존 여부를 지정(재정렬 시에도 묶음 유지, 다른 미션 goal이 사이에 끼지 못함).
배송 가능여부 견적: 배차 전 관제가 quote/offer로 후보 로봇에 사전 견적을 질의하면 로봇이 quote/bid로 수행 가능 여부·ETA를 회신합니다. 미션을 만들지 않고 낙찰이 없는 2단계(질의 → 견적)이며, 배차 입찰과는 토픽을 분리(quote/*)해 운영합니다. 응답(bid) 스키마는 배차 입찰과 동일하고, 질의(offer) 본문만 축약형입니다.
상태 어휘: 로봇·goal·mission 세 계층의 status는 같은 어휘를 씁니다 — standby · doing · done(취소 canceled).
인증: 사전 등록된 robotCode로 비밀키 발급(REST, 관제가 내부 robotId 회신) → X.509 인증서 번들(다운로드 URL)로 MQTT에 연결. REST 인증 요청에는 HMAC-SHA256 서명 헤더(X-Robot-Signature) 부착.
메시징: REST는 등록·인증·맵 등록에 사용. 이후 로봇↔관제 전 메시지는 방향 프리픽스 토픽(s2r/r2s)의 MQTT 단일 채널로 주고받습니다(상태·알람·미션·입찰·PIN·박스).

2. 로봇(제로웍스)이 구현할 책임

구분	책임	채널
인증	비밀키·인증서 발급 수신(REST), 인증서로 MQTT 연결	REST
맵 등록	UI 버튼으로 지도·노드를 `siteId`·제시 `mapId` 기준 업로드(등록 개시 → 업로드 URL에 PUT → commit)	REST
미션 입찰	입찰 요청(`offer`) 수신 → goal별 예상 도착시간 자체 계산해 입찰(`bid`) 회신 → 배차 결과(`result`) 수신	MQTT
배송 가능여부 견적	견적 질의(`quote/offer` — `quoteId`·`deliveryType`·목적지 요약의 축약 본문) 수신 → goal별 수행 가능 여부·도착 예상 시각(`available`·`estArrival`) 회신(`quote/bid`). 응답 형식은 배차 입찰과 동일, 입찰과 달리 미션 미생성·낙찰 없음	MQTT
goal 수행	낙찰 goal을 `arrivalOrder` 순으로 수행, 진행 상태(`standby/doing/done`·progress·estArrival) 발행. 관제가 발급한 goal·mission id 를 그대로 echo	MQTT
상태·알람	상태/배터리/위치 발행(retain, 변동 필드만). 보행자 안전 이벤트·소프트웨어 인벤토리 발행. 이상 시 알람(`code·level·msg`) 발행	MQTT
인프라 요청	엘베·로비폰이 필요한 시점에 `r2s/{robot_id}/resource`로 관제에 요청 → `resource/ready` 수신 후 진행. 탑승·하차 완료 보고 필수(누락 시 엘베 콜 취소), 탑승 불가 시 로봇이 `status: "cancelByRobot"`으로 자진 취소도 가능	MQTT
PIN 검증	`goal.mission[].PIN`으로 로컬 검증 후 지정 도어 개방, 사용·검증 결과를 관제에 감사 이벤트로 보고	MQTT
적재함	관제가 `goal.mission[].door`(`door1`~`doorN`)로 지정한 칸을 열고/잠금 (칸 선택은 관제가 결정, 점주 임의 선택 불가). 칸 수 `N`은 로봇별 설정	MQTT
상차·하차 완료 보고	박스를 닫으면 해당 `pickup`/`dropoff` mission 을 `done`으로 발행 → 상차 `done`이 배달 출발 트리거, 하차 `done`이 수령 완료	MQTT
취소 사유 발행	수행 불가 시 goal·mission 을 `canceled` + `reason`으로 발행 (사유 없는 취소는 관제에 기록되지 않음)	MQTT

3. 선결 조건·협의 항목

아래는 1.5차 결합 전 제로웍스와 확정해야 할 항목입니다. 확정 시 연동 API 문서의 해당 페이로드를 잠급니다.

토픽 네임스페이스 — 방향 프리픽스(s2r/r2s) 토픽의 브로커 정책(ACL) 매핑 확정.
입찰 타임아웃 — 단발 라운드의 bid 타임아웃 값 합의(마감 후 지각 bid 배제, 재오퍼 없음). 배송 가능여부 견적(quote/*) 라운드도 동일 타임아웃 모델을 따르며, 무응답은 available=false로 간주합니다.
mission.atomic 묶음 순서 보존 — goal.type: waiting/none 의미, arrivalOrder 동률·미지정 처리, 한 미션 goal 다수(예: 5개 이상) 시 배차 정책.
PIN 감사 이벤트 — 로봇 키패드 PIN 입력 경로의 사용·결과 보고(r2s) 토픽·페이로드 형식 확정.
retain 적용 범위 — state·software=사용, 이벤트=미사용.
적재 상태 정합 — 예외 시 서버·로봇 적재 인식 불일치를 파악할 별도 값 검토 (제로웍스 펌웨어).
맵 노드 idx 안정성 — 재등록 시 노드 idx가 유지되는지(관제 목적지 키의 원천). 밀리면 기존 주소 매핑이 다른 세대를 가리킵니다.
미해결 요청 사항 — state.status의 unused·빈 문자열 정리, r2s/resource의 orderId에 주문번호 사용(현재 로봇 내부 스텝 id 관측), 로봇 시계 NTP 동기(estArrival 절대 시각 정확도).
인증서 발급·저장 방식 (TPM 활용 여부), 네트워크 환경(VPN / 공용망 / 게이트웨이).