제로웍스 로봇이 비스캣 코어와 결합해 한 사이클을 도는 동작 흐름입니다.
엔드포인트·페이로드 상세는 연동 API 문서를, 메인은 개발 가이드를 참조하세요.
1. 등록·인증 (최초 1회)
비스캣 관제에 robotId가 사전 등록된 뒤, 로봇은 공개키를 제출해 HMAC 비밀키를 1회 발급받고 X.509 인증서를 내려받습니다. 이후 모든 REST 요청에 서명을 부착합니다.
sequenceDiagram
participant R as 로봇(제로웍스)
participant C as 비스캣 코어
Note over R,C: robotId는 관제에 사전 등록된 상태
R->>C: POST /v1/robot/key (robotId, publicKey)
C-->>R: 공개키로 암호화된 HMAC 비밀키
R->>C: POST /v1/robot/cert (HMAC 서명)
C-->>R: 인증서 다운로드 URL (1회용)
Note over R: 비밀키·인증서 보관 (TPM 권장)
비밀키는 1회만 발급됩니다. 재요청 시 409 ROBOT_ALREADY_ACTIVATED.
이후 요청 헤더: X-Robot-ID, X-Robot-Ts(ISO8601), X-Robot-Signature(HMAC-SHA256). timestamp는 ±60초 윈도우.
2. FMS 폴링·미션 점유
로봇은 단일 엔드포인트 POST /v1/fms/command를 두 모드로 사용합니다. 요청 모드로 상태를 보고하며 미션을 받고, 수행 가능하면 응답 모드로 executionTime=0을 보고해 점유를 시도합니다. anyone 타입이므로 먼저 보고한 로봇이 점유하고, 나머지는 already_claimed로 거절됩니다.
sequenceDiagram
participant R as 로봇
participant C as 코어 (대기 큐)
loop 폴링 주기
R->>C: POST /v1/fms/command (mode=request, robotMode·battery·position)
alt 후보 미션 있음
C-->>R: commands[] (commandId, missionId, type=anyone, missionType)
R->>C: POST /v1/fms/command (mode=response, executionTime=0)
alt 먼저 보고 → 점유
C-->>R: claimed[]
else 다른 로봇이 선점
C-->>R: rejected[] (already_claimed)
end
else 미션 없음
C-->>R: commands: []
end
end
점유 확정 시점
점유는 executionTime=0 보고가 코어에 도달해 Redis 대기 큐에서 원자적으로 제거되는 순간 확정됩니다. DB 락이 아니라 큐의 원자적 제거로 경쟁을 해소합니다. 폴링은 429 수신 시 지수 백오프를 적용하세요.
3. 배송 미션 전체 시나리오
점유 이후의 한 사이클입니다. PIN 검증·박스 칸 개방·박스 닫힘(출발 트리거)이 로봇 책임으로 포함됩니다.
sequenceDiagram
participant R as 로봇
participant C as 코어
participant O as 오토메타(앱 표출)
Note over R: 미션 점유 완료 (배송)
R->>C: 매장 이동 → arrived(매장) 이벤트 (SQS)
C->>O: #7 매장 도착 통지
Note over R: 점주가 KDS에 점주PIN 입력
R->>C: pin_verify_request (owner) (SQS)
C-->>R: pin_verify_result + box_assign(칸 지정) (MQTT)
Note over R: 지정 칸 개방 → 점주 상차 → 박스 닫힘
R->>C: box_closed 이벤트 (SQS) = 출발 트리거
C->>O: #8 배달 출발 알림
R->>C: 세대 이동 → arrived(세대) 이벤트 (SQS)
C->>O: #9 도착 통지
Note over R: 사용자가 박스 키패드에 사용자PIN 입력
R->>C: pin_verify_request (user) (SQS)
C-->>R: pin_verify_result + box_assign(개방) (MQTT)
Note over R: 하차 완료 → 복귀
R->>C: unloaded / 미션 완료 보고 (SQS)
C->>O: #9 하차 완료 통지
매장 이동·도착: 점유 후 매장으로 주행. 도착 시 arrived 이벤트 보고. 코어가 오토메타에 매장 도착(#7)을 통지.
점주 PIN 검증: 점주가 KDS에 고정 PIN 입력 → 로봇이 pin_verify_request(owner) 전송 → 코어가 대조 후 결과와 함께 열 칸(boxSlot)을 지시(box_assign).
상차·박스 닫힘: 점주 상차 후 박스를 닫으면 로봇이 box_closed 이벤트 보고. 이 이벤트가 배달 출발 트리거이며, 코어가 오토메타에 배달 출발(#8)을 통지.
세대 이동·도착: 세대로 주행, 도착 보고. 코어가 도착 통지(#9).
사용자 PIN 검증·하차: 사용자가 박스 외부 키패드에 랜덤 PIN 입력 → pin_verify_request(user) → 코어 대조 후 해당 칸 개방 지시 → 하차.
완료·복귀: 하차 완료 보고 후 복귀. 코어가 하차 완료(#9)를 통지하고 미션을 종료.
칸 할당은 코어가 결정
4칸 적재함의 어느 칸을 쓸지는 관제(코어)가 주문 수량 기반으로 결정합니다. 점주가 임의로 칸을 고를 수 없으며, 로봇은 box_assign 지시에 따라 해당 칸만 개방합니다. 주문 수량이 4칸을 초과하면 배차 단계에서 거부됩니다.
4. 쓰레기 수거 시나리오
미션 타입 trash_pickup. 흐름은 배송과 동일한 FMS 점유·주행 구조를 따르되, 매장↔세대 대신 세대(수거 요청 지점) → 처리 지점 경로이고 점주 PIN 단계가 없습니다. 세부 적재·개폐 동작은 제로웍스 펌웨어 capability에 맞춰 협의 시 확정합니다.
5. 단지 인프라(E/V·로비폰) 처리
로봇은 엘리베이터·로비폰을 직접 호출하지 않습니다
엘리베이터 호출·문 열림·홀콜 등록은 코어가 단지서버 inBase를 경유해 처리합니다. 로봇은 자신의 위치·상태·도착 이벤트만 보고하면 되고, 인프라 제어 책임은 지지 않습니다. 코어가 로봇 위치를 기준으로 적절한 시점에 inBase를 호출합니다.
단, 고척 PoC는 현대엘리베이터 "로봇 비탑승" 입장에 따라 단지서버 우회 연동을 검토 중입니다. 이 경우 실패 시나리오(호출 실패·문 안 열림·층 오인식) 대응을 별도 협의합니다.
6. 에러·리플래닝·재시도
점유 실패:rejected(already_claimed|expired|mode_mismatch) 수신 시 폴링 루프로 복귀해 다음 미션을 대기.
통신 실패: SQS 이벤트 전송 실패·MQTT 미수신 시 재시도. 보고 누락 복구를 위해 코어는 위치/상태 폴(오토메타 #5·#6) 경로를 별도로 둡니다.
PIN 불일치·만료:pin_verify_result.ok=false + 사유(reason) 수신. 칸을 열지 않고 재입력 대기.
리플래닝: 1차는 자리만 마련된 단계. 코어가 replan 스트림으로 경로 수정을 내릴 수 있으며, 로그로 적재됩니다.