> For the complete documentation index, see [llms.txt](https://freegrow-1.gitbook.io/product-docs-kr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://freegrow-1.gitbook.io/product-docs-kr/creatorkit_q1/gateway/mqtt.md).

# MQTT 데이터 형식

GrowSpace UWB 게이트웨이는 위치 측위를 위한 다양한 데이터를 MQTT 프로토콜을 통해 실시간 전송합니다.

### 이 글에서는 

**MQTT-Studio를 통해 수신되는 데이터의 종류와 형식**을 구체적으로 정리하여, 장치 상태 확인이나 위치 시스템 연동 시 유용하게 활용할 수 있도록 안내합니다.

***

### MQTT 데이터는 어떻게 확인하나요?

게이트웨이에서 전송되는 데이터는 MQTT-Studio에서 구독한 Topic을 통해 확인할 수 있습니다.

* **Topic 예시:**
  * `uwb/gateway/start/#`
  * `uwb/gateway/config/#`
  * `uwb/gateway/devices/#`

MQTT-Studio에서 해당 메시지를 클릭하면 상세 JSON 데이터를 확인할 수 있으며,\
우측의 **복사 버튼**을 클릭하면 텍스트 형태로 복사하여 메모장 등에서 쉽게 분석할 수 있습니다.

***

### 데이터 종류별 예시 및 설명

GrowSpace 게이트웨이에서 전송되는 주요 데이터는 다음과 같이 4가지로 나뉩니다.

***

#### Start 데이터

* **전송 시점:** 게이트웨이 부팅 직후 한 번만 전송
* **목적:** 장치 부팅 확인 및 네트워크 연결 상태 확인

게이트웨이가 전원을 공급받고 정상적으로 부팅되면, 시스템 초기 상태를 알리는 `start` 메시지를 전송합니다.\
이 메시지를 통해 해당 게이트웨이 장비의 ID, Pan ID, 현재 IP 주소를 확인할 수 있습니다.

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2FiAXbzBE3rIpOFgP8vVhh%2Fimage.png?alt=media&amp;token=9f39506d-0646-4944-8bb2-2a4039ab458a" alt=""><figcaption></figcaption></figure>

```json
{
  "uwbID": "GR21BA",
  "panID": "0001",
  "ip": "172.30.1.177"
}
```

**활용 예:**

* 게이트웨이가 네트워크에 정상 연결되었는지 확인할 때
* 디바이스 식별 및 설치 위치 확인 시

***

#### Config 데이터

* **전송 시점:** 일정 주기마다 반복 전송
* **목적:** 장비 생존 신호(Heartbeat)

게이트웨이가 지속적으로 작동 중이라는 사실을 알리기 위해 주기적으로 전송되는 상태 데이터입니다.\
형식은 `start` 데이터와 동일하지만, **지속적인 생존 신호용**으로 구분됩니다.&#x20;

Config 데이터의 전송 주기는 기본적으로 10초에 한 번입니다.

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2FA5PJqFYUCPkdRSz7ETQf%2Fimage.png?alt=media&amp;token=25721104-772a-4dfd-8dba-0d840557527d" alt=""><figcaption></figcaption></figure>

```json
{
  "uwbID": "GR21BA",
  "panID": "0001",
  "ip": "172.30.1.177"
}
```

**활용 예:**

* 시스템의 온라인 상태 확인
* 장비 장애 감지 또는 네트워크 단절 탐지

***

#### Anchor 정보 (devices – anchors)

* **전송 시점:** 게이트웨이가 앵커를 인식했을 때
* **목적:** 기준점(앵커)의 위치 및 역할 전달

게이트웨이가 인식한 **UWB 앵커의 ID, 좌표, Pan ID, initiator 여부** 등이 포함된 메시지입니다.\
이 정보는 위치 계산의 기준이 되는 앵커 데이터를 구성하는 데 사용됩니다.

앵커 데이터는 전송 주기를 수정할 수 없으며, 감지 시점 또는 시스템 내부 로직에 따라 자동 전송됩니다.

```json
{
  "gatewayID": "GR21BA",
  "anchors": [
    {
      "id": "GR365d",
      "panID": "0001",
      "initiator": true,
      "x": -2.92,
      "y": 0.35,
      "z": 0.00
    }
  ]
}
```

**활용 예:**

* 앵커 위치 등록 자동화
* 시스템 지도 구성 시 기준점 매핑

***

#### 태그 위치 정보 (devices – tags)

* **전송 시점:** 위치 계산이 완료될 때마다 반복 전송
* **목적:** 실시간 위치 추적

게이트웨이는 UWB 태그들의 현재 위치 좌표(x, y, z)를 계산해 하나의 메시지로 전송합니다.\
한 번의 메시지에 여러 태그가 포함되어 전송될 수 있으며, `gatewayID`, `panID`, `tag ID`, `좌표값`으로 구성됩니다.

태그 데이터의 전송 주기는 태그 장치에서 aurs 명령어 설정을 통해 사용자가 직접 변경할 수 있습니다.

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2FnqkX1doqUGTmGTmNcIs3%2Fimage.png?alt=media&amp;token=67dd0987-6562-4532-b98e-75c2184c1d05" alt=""><figcaption></figcaption></figure>

```json
{
  "gatewayID": "GR21BA",
  "tags": [
    {"id":"GR2c3c", "panID":"0001", "x": -3.95, "y": 0.23, "z": -2.48},
    {"id":"GR1012", "panID":"0001", "x": -1.48, "y": 3.42, "z":  0.66},
    {"id":"GR2eba", "panID":"0001", "x": -4.27, "y": 0.20, "z": -2.36}
  ]
}
```

**활용 예:**

* 실시간 위치 시각화 대시보드 연동
* 태그 이동 경로 분석
* 출입 감지, 위험 구역 침입 경고 등 지오펜스 구성

***

### 정리 및 활용 팁

| 데이터 유형  | MQTT Topic              | 전송 목적               |
| ------- | ----------------------- | ------------------- |
| Start   | `uwb/gateway/start/#`   | 게이트웨이 부팅 상태 확인      |
| Config  | `uwb/gateway/config/#`  | 장치 작동 여부 확인 (생존 신호) |
| Anchors | `uwb/gateway/devices/#` | 앵커 정보 제공            |
| Tags    | `uwb/gateway/devices/#` | 태그 위치 데이터 전송        |

* Topic 내 `projectId`는 API 키 기반으로 구성되며, 각 시스템 별로 다르게 나타납니다.
* 실시간 디버깅 또는 시스템 검증 시 **Start → Config → Devices 흐름으로 정상 수신 여부**를 확인하세요.