# MQTT 데이터 연동

### 개요

Q2 Starter Kit의 미니 PC에는 **MQTT 브로커가 사전 탑재**되어 있어, 별도 서버 구축 없이 사내 시스템을 구독자로 붙이는 것만으로 실시간 위치·이벤트 데이터를 받을 수 있습니다.

* 모든 데이터는 **사내 전용망 내부**에서만 흐르며, 외부 클라우드를 경유하지 않습니다.
* 표준 MQTT 프로토콜을 따르므로 **별도 SDK가 필요 없습니다.** (Python · Node.js · Java · Go · n8n · Node-RED 등 기존 도구로 바로 연결)

***

### 데이터 흐름

```
   [Tag · Anchor]
         │ (UWB)
         ▼
    [Gateway Q2] ──── publish ────┐
                                  ▼
                       ┌──────────────────────┐
                       │  MQTT 브로커          │
                       │  (미니 PC 내장)        │
                       └──────────────────────┘
                          ▲                ▲
                    subscribe         subscribe
                          │                │
                  [관제 PC]        [사내 시스템]
                                   ERP · MES · 자체 대시보드
```

***

### 사전 준비

* [ ] 구독할 사내 시스템(PC · 서버)이 미니 PC와 **동일한 사내망**에 연결되어 있는지 확인
* [ ] 미니 PC의 호스트명(`q2-server.local`) 또는 IP 주소 확인
* [ ] MQTT 클라이언트 라이브러리 또는 디버깅 도구 준비 (예: `mosquitto_sub`, MQTT Explorer)

***

### 확인할 수 있는 데이터

Q2는 크게 **두 방향**의 토픽을 운영합니다.

#### 1.  Gateway → Server (게이트웨이가 발행하는 데이터)

현장에서 실제로 측위된 **위치 · 장비 상태 데이터**입니다. 사내 시스템 연동 시 가장 많이 사용됩니다.

| 토픽                                            | 확인 가능한 데이터           | 발행 주기       |
| --------------------------------------------- | -------------------- | ----------- |
| `q2/gateway/{gatewayId}/position`             | 태그별 실시간 좌표 (x, y, z) | 100ms       |
| `q2/gateway/{gatewayId}/status`               | 게이트웨이 동작 상태          | 30초         |
| `q2/gateway/{gatewayId}/anchor/status`        | 앵커 배터리 · 펌웨어 버전      | 이벤트 발생 시    |
| `q2/gateway/{gatewayId}/anchor/list`          | 현재 감지 중인 앵커 목록       | 이벤트 발생 시    |
| `q2/gateway/{gatewayId}/calibration/status`   | 칼리브레이션 진행 상태         | 칼리브레이션 중    |
| `q2/gateway/{gatewayId}/calibration/response` | 칼리브레이션 거리 측정값        | 칼리브레이션 중    |
| `q2/gateway/{gatewayId}/calibration/ack`      | 칼리브레이션 완료 알림         | 칼리브레이션 종료 시 |
| `q2/gateway/{gatewayId}/calibration/cancel`   | 칼리브레이션 취소 응답         | 취소 시        |
| `q2/gateway/{gatewayId}/debug/calibration`    | 칼리브레이션 디버그 (BASE64)  | 칼리브레이션 중    |
| `q2/server/tag/{address}/status`              | 태그 배터리 · 펌웨어 · 주기 정보 | T3 프레임 수신 시 |

{% hint style="info" %}
💡`{gatewayId}` · `{address}` 부분은 장비마다 다르며, 관제 프로그램에서 확인할 수 있습니다. 와일드카드(`+`)를 사용하면 여러 장비의 데이터를 한 번에 구독할 수 있습니다.<br>

예: `q2/gateway/+/position` → 모든 게이트웨이의 위치 데이터 일괄 구독
{% endhint %}

#### 2.  Server → Gateway / Client (서버가 발행하는 데이터)

관제 프로그램에서 설정한 **명령 · 변경 이벤트 · 알림**입니다. 사내 시스템에서 설정 변경 사항을 추적하거나 알림을 받을 때 사용합니다.

| 토픽                                          | 확인 가능한 데이터                     |
| ------------------------------------------- | ------------------------------ |
| `q2/notification`                           | 배터리 · 지오펜스 · 연결 등 일반 알림        |
| `q2/devices/tags`                           | 전체 태그 목록 스냅샷 (10초 주기)          |
| `q2/devices/anchors`                        | 전체 앵커 목록 스냅샷 (10초 주기)          |
| `q2/server/tag/{address}/update`            | 태그 등록 · 수정 · 삭제 이벤트            |
| `q2/server/tag/assign/{address}`            | 태그-작업자 할당 · 해제                 |
| `q2/server/anchor/{address}`                | 앵커 등록 · 수정 · 삭제 이벤트            |
| `q2/server/anchor/coordinates`              | 칼리브레이션 완료 후 전체 앵커 좌표           |
| `q2/server/geofence/{geofenceId}`           | 지오펜스 등록 · 수정 · 삭제 이벤트          |
| `q2/server/gateway/{gatewayId}/config`      | 게이트웨이 설정 변경 (PAN ID · API Key) |
| `q2/server/calibration/command`             | 칼리브레이션 명령 (전체 브로드캐스트)          |
| `q2/server/calibration/command/{gatewayId}` | 칼리브레이션 명령 (특정 게이트웨이)           |
| `q2/server/calibration/status`              | 칼리브레이션 진행 상태                   |

***

### 페이로드 예시 — 태그 위치 데이터

가장 많이 사용되는 `q2/gateway/{gatewayId}/position` 토픽 예시입니다.

```json
{
  "panId": 39321,
  "floorId": 1,
  "tags": [
    {
      "address": "0x0001",
      "x": 1.23,
      "y": 4.56,
      "z": 0.0,
      "origin_x": 1.20,
      "origin_y": 4.50,
      "origin_z": 0.0,
      "worker_name": "홍길동"
    }
  ],
  "timestamp": 1730000000000
}
```

| 필드                                          | 의미                            |
| ------------------------------------------- | ----------------------------- |
| `panId`                                     | PAN(Personal Area Network) ID |
| `floorId`                                   | 층 식별자                         |
| `tags[].address`                            | 태그 고유 주소                      |
| `tags[].x` · `y` · `z`                      | 보정 후 좌표 (단위: m)               |
| `tags[].origin_x` · `origin_y` · `origin_z` | 보정 전 원본 좌표 (단위: m)            |
| `tags[].worker_name`                        | 태그-작업자 할당 시의 작업자명             |
| `timestamp`                                 | 발행 시각 (Unix epoch, ms)        |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://freegrow-1.gitbook.io/product-docs-kr/q2-starterkit/mqtt.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.