Vision MQTT 스키마

---

개요

항목	내용
작성 주체	Vision 팀
최종 수정일	2026-10-04
수정 내용	준비물 챙기기 쪽 라벨 수정

토픽 목록

구분	Topic (바로가기)	방향	설명
REQUEST	server/session/start	서버 → Vision	세션(페르소나)이 시작됐음을 알림
REQUEST	server/session/end	서버 → Vision	세션(페르소나)이 끝났음을 알림
RESPONSE	cctv/person/zone	Vision → 서버	현재 추적 중인 사람이 위치한 zone
RESPONSE	cctv/person/emotion	Vision → 서버	현재 추적 중인 사람의 표정 인식 결과
RESPONSE	vision/position/spot	Vision → 서버	현재 추적 중인 Spot 의 위치
RESPONSE	cctv/person/profile	Vision → 서버	현재 추적 중인 사람의 외형 설명 (세션당 1회)
RESPONSE	cctv/item/state	Vision → 서버	CCTV 내 미리 설정된 영역내 물건의 위치 여부 상태 (초당 1회)
REQUEST	server/pokemon/start	서버 → Vision	해당 포켓몬의 포획 판정을 시작하라는 알림
REQUEST	server/trash/start	서버 → Vision	쓰레기의 플로깅 판정을 시작하라는 알림
RESPONSE	cctv/pokemon/complete	Vision → 서버	해당 포켓몬 포획 완료
RESPONSE	cctv/trash/complete	Vision → 서버	플로깅(쓰레기 줍기) 완료
RESPONSE	cctv/person/action	Vision → 서버	현재 추적 중인 사람의 동작 라벨 (동작이 바뀔 때)

---

SERVER -> VISION

Topic: server/session/start

방문객이 시작 장소에서 페르소나를 시작하면, 백엔드가 session_id를 Vision에 보내줍니다.

Payload

{
  "session_id": "string" // 오케스트레이션 서버 발급값
}

필드	타입	필수	설명
session_id	string	Y	오케스트레이션 서버에서 발급하는 세션 식별자

예시

{
  "session_id": "abc123"
}

---

Topic: server/session/end

방문객의 체험이 모두 끝나면, 백엔드가 session_id를 Vision에 보내줍니다.

Payload

{
  "session_id": "string" // 오케스트레이션 서버 발급값
}

필드	타입	필수	설명
session_id	string	Y	오케스트레이션 서버에서 발급하는 세션 식별자

예시

{
  "session_id": "abc123"
}

---

VISION -> SERVER

Topic: cctv/person/zone

세션의 주체가 위치한 zone을 발행합니다.

Payload

{
  "session_id": "abc123",
  "zone_id": "home"
}

필드	타입	필수	설명
session_id	string	Y	세션 id
zone_id	string	Y	현재 위치한 zone. 어느 zone 에도 속하지 않으면 none

서버가 알아둬야 하는 부분

• 위치 변경이 있을 시에만 발행됩니다.
• 등록된 사람이 프레임에서 사라졌다가 다른 zone 에서 다시 잡히면 그때 새 zone 이 발행됩니다.
• 세션이 바뀌면 이전 세션의 zone 과 같더라도 새 session_id 로 다시 발행됩니다.

---

Topic: cctv/person/emotion

세션의 주체(페르소나를 시작한 사람)의 표정이 바뀔 때만 발행합니다. 내부적으로 0.5초마다 판정합니다. 표정 변경 시에만 발행됩니다.

Payload

{
  "session_id": "abc123",
  "timestamp": 1690000000.123,
  "emotion": "joy"
}

필드	타입	필수	설명
session_id	string	Y	세션 id
timestamp	number	Y	Unix epoch 초 (소수점 포함)
emotion	string	Y	인식된 표정(joy, surprise, neutral, anger)

값	의미
joy	기쁨
surprise	놀람
neutral	중립
anger	화남

서버가 알아둬야 하는 부분

• 표정에 변경이 있을 시에만 발행됩니다.
• 얼굴이 잡히지 않으면 발행되지 않습니다.

---

Topic: vision/position/spot

Spot의 위치를 발행합니다. (1초 주기)

Payload

{
  "session_id": "abc123",
  "timestamp": 1690000000.123,
  "x": 100.0,
  "y": 100.0,
  "zone_id": "home"
}

필드	타입	필수	설명
session_id	string	Y	세션 id. 열린 세션이 없으면 "none"
timestamp	number	Y	Unix epoch 초 (소수점 포함)
x	number	Y	월드 좌표 X (cm)
y	number	Y	월드 좌표 Y (cm)
zone_id	string	Y	현재 위치한 zone. 어느 zone에도 없으면 "none"

서버 처리

• 서버는 이 토픽을 구독해 zone_id를 백오피스 장소(locations.zone_id)로 매핑한 뒤 orchestration/{sessionId}/spot/position(retained)으로 재발행한다. 자세한 내용은 MQTT_SCHEMA-ORCHESTRATION_SERVER §20 참고.

---

좌표계

사람 위치, 스팟 위치·방향, zone은 모두 같은 월드 좌표계를 공유

항목	정의
원점 (0, 0)	체험 시작 지점 (변동 가능성 있음)
단위	cm. [x, y] = [100, 50] 이면 원점에서 x방향 1m, y방향 0.5m 지점
축	바닥 평면의 x, y 두 축. 방향은 캘리브레이션 시 원점 마커의 축으로 정의 (전시장 벽과 정확히 평행하지 않을 수 있음)
카메라	천장 카메라 4대(51/52/53/54)를 공통 캘리브레이션 — 모든 카메라가 같은 좌표계 공유

참고

• 맵 이미지에 찍으려면 "월드 cm → 맵 픽셀" 변환이 필요할 것 같습니다.
• 각 zone이 어느 좌표에 위치해 있는지도 필요하실 것 같은데요. https://github.com/zero1ne-26/doc/wiki/바닥좌표계 를 봐주시면 될 것 같습니다.

---

Zone 정의

전시장 내 5개 구역 정의

zone_id	장소
vehicle	차량
park	공원
home	집
mart	마트

• 어느 zone 에도 속하지 않으면 zone_id 는 none 으로 나갑니다.

---

Topic: cctv/person/profile

세션의 주체의 겉모습을 VLM 이 줄글로 설명해 발행합니다. 세션 당 한 번 발행됩니다.

Payload

{
  "session_id": "abc123",
  "description": "20대 초반으로 보이는 여성으로, 검은 머리를 뒤로 묶었다. 흰색 후드티에 검은색 바지, 흰색과 검은색이 섞인 운동화를 신었다. 안경이나 모자는 쓰지 않았고 가방은 없다."
}

필드	타입	필수	설명
session_id	string	Y	세션 id
description	string	Y	외형 설명

---

QoS / 기타 설정

항목	내용
QoS	1
Retain	false
기타

---

Item find

find specific item in cctv using trained network.

Topic: cctv/item/state

cctv로 home table 에 있는 물건을 식별하고, 영역 밖에 있는지 확인합니다.

Payload

{
  "I1": 1,
  "I2": 1,
  "I3": 1,
  "I4": 1,
  "I5": 1,
}

필드	타입	필수	설명
I1	char	Y	item 1 states, 0x01 in zone, 0x02 out of zone, 0x03 Null
I2	char	Y	item 2 states, 0x01 in zone, 0x02 out of zone, 0x03 Null
I3	char	Y	item 3 states, 0x01 in zone, 0x02 out of zone, 0x03 Null
I4	char	Y	item 4 states, 0x01 in zone, 0x02 out of zone, 0x03 Null
I5	char	Y	item 5 states, 0x01 in zone, 0x02 out of zone, 0x03 Null

• item 1 : 도시락통
• item 2 : 노트
• item 3 : 파우치
• item 4 : 유치원가방
• item 5 : 텀블러

---

공원 미션 (포켓몬 포획 / 플로깅)

공원의 포켓몬 인형 3종과 쓰레기는 각각 미리 그려둔 구역(zone)을 갖습니다. start 를 보낸 물건만 판단하며, 미션을 완료하면 complete 를 발행합니다.

Topic: server/pokemon/start

해당 포켓몬의 포획 미션을 시작합니다.

Payload

{
  "session_id": "abc123",
  "pokemon": "psyduck"
}

필드	타입	필수	설명
session_id	string	Y	세션 id
pokemon	string	Y	포획할 포켓몬 (psyduck, wobbuffet, exeggutor)

값	의미
psyduck	고라파덕
wobbuffet	마자용
exeggutor	나시

---

Topic: server/trash/start

쓰레기의 플로깅 미션을 시작합니다.

Payload

{
  "session_id": "abc123"
}

필드	타입	필수	설명
session_id	string	Y	세션 id

---

Topic: cctv/pokemon/complete

포켓몬을 포획하여 미션을 완료하면 발행됩니다.

Payload

{
  "session_id": "abc123",
  "pokemon": "psyduck"
}

필드	타입	필수	설명
session_id	string	Y	세션 id
pokemon	string	Y	포획된 포켓몬 (psyduck, wobbuffet, exeggutor)

---

Topic: cctv/trash/complete

쓰레기를 주워 플로깅을 완료하면 발행됩니다.

Payload

{
  "session_id": "abc123"
}

필드	타입	필수	설명
session_id	string	Y	세션 id

---

참고

vision 팀에서 보고 있는 비전용 대시보드가 따로 있는데요. 그쪽에서는 아래 멘트를 사용하고 있습니다. 그냥 참고만 해주세요!

대상	start	complete
psyduck	주변에 노란색 오리 포켓몬인 고라파덕이 출몰했다!	신난다-! 고라파덕을 붙잡았다!
wobbuffet	주변에 파란색 샌드백 포켓몬인 마자용이 출몰했다!	신난다-! 마자용을 붙잡았다!
exeggutor	주변에 야자수 포켓몬인 나시가 출몰했다!	신난다-! 나시를 붙잡았다!
쓰레기	주변에 쓰레기가 있습니다. 플로깅 활동을 하면서 체력을 길러봅시다!	쓰레기를 주웠다! 건강도 챙기고 환경도 챙기고!

---

Topic: cctv/person/action

사람의 action을 실시간으로 감지합니다.

Payload

{
  "session_id": "abc123",
  "action_label": "squat down"
}

필드	타입	필수	설명
session_id	string	Y	세션 id
action_label	string	Y	행동 라벨

서버 측 해석 (2026-09-19) — Vision은 감지한 동작 1건만 발행하고, 태스크 완료 판정에는 관여하지 않는다. 오케스트레이션 서버는 type='person_action' 태스크에 매핑된 action_labels[]를 AND 조건으로 본다 — 배열의 동작을 전부 달성해야 태스크가 완료된다(순서 무관, 달성분은 유지). 달성/미달성 현황은 서버가 태블릿에 tasks[].action_progress.{cleared,remaining}으로 내려보낸다.

도착 직후 무시 구간 (2026-09-20) — 서버는 세션이 그 태스크의 장소에 도착한 시각을 기준으로, app_settings.person_action_arrival_delay_seconds(기본 5초)가 지나기 전에 수신한 cctv/person/action은 무시한다. 도착 직후 카메라 프레임이 안정화되기 전 오탐으로 태스크가 로딩 중인데도 완료된 것처럼 보이는 문제를 막기 위함 — Vision 쪽 발행 로직 변경은 필요 없다.

자세한 내용은 오케스트레이션 서버 스키마를 참고.

action label 종류

저희 프로젝트에서 나올 수 있는 라벨들입니다. 아래 라벨들 외의 action은 검출되지 않습니다! 행동이 변경되었을 시에만 발행됩니다.

action label	동작 설명	사용된 데이터
sitting down	서 있다가 앉는 동작	NTU60
standing up (from sitting position)	앉아 있다가 일어서는 동작	NTU60
squat down	스쿼트처럼 무릎을 굽혀 쪼그려 앉는 동작	NTU120
jump up	제자리에서 위로 점프	NTU60
hopping (one foot jumping)	한 발로 폴짝폴짝 뛰기	NTU60
running on the spot	제자리 뛰기	NTU120
side kick	옆으로 발차기	NTU120
kicking something	앞으로 발로 차는 동작	NTU60
hand waving	손을 좌우로 흔들어 인사	NTU60
cheer up	두 팔을 위로 들기	NTU60
put the palms together	두 손바닥을 가슴 앞에 모음 (합장)	NTU60
cross arms	팔짱 끼기	NTU120
arm circles	팔을 크게 원으로 돌리기	NTU120
arm swings	팔을 앞뒤로 흔들기	NTU120
stretch oneself	기지개 켜기	NTU120
touch head (headache)	머리를 손으로 짚음 (두통)	NTU60
touch neck (neckache)	목을 손으로 짚음 (목 결림)	NTU60

---