> 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/undefined.md).

# 직접 서버 구축하기

### 이 글에서는 

MQTT-Studio를 사용해 **Mosquitto 브로커에 접속하고**, **GrowSpace 게이트웨이에서 전송되는 UWB 실시간 위치 데이터를 구독하는 방법**을 안내합니다.

MQTT 브로커를 통해 태그 및 앵커의 위치 데이터를 **서버 또는 클라우드 시스템과 연동**하고자 할 때,\
이 글의 과정을 따라 MQTT 구독 환경을 먼저 설정해 두면, 이후 데이터 연동이 훨씬 수월해집니다.

> ⚠️ MQTT 서버(Mosquitto 브로커)를 처음 설치하거나 구성하려는 경우,\
> 아래 문서를 먼저 참고해 서버 환경을 준비해 주세요.\
> [MQTT 서버 구축 가이드 보러 가기](https://freegrow-1.gitbook.io/product-docs/creatorkit_q1/undefined-1/mqtt)

하지만 서버 구축 이전이라도,\
**MQTT-Studio를 사용한 테스트 환경 구성은 별도로 먼저 설정해볼 수 있으므로**,\
이 글의 내용을 먼저 따라하며 브로커 접속과 데이터 구독 과정을 익혀보는 것을 추천드립니다.

***

### MQTT-Studio 프로젝트 생성

#### 프로젝트 생성

* MQTT-Studio를 실행합니다.
* 좌측 메뉴에서 **New Project**를 클릭합니다.

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2FHuJHQVjRU9BVWQgZ3u8N%2Fimage.png?alt=media&amp;token=0d4dcae0-a358-4c88-9cf7-a91e5bede496" alt=""><figcaption></figcaption></figure>

* 아래 항목을 입력합니다.

| 항목                      | 설명                                |
| ----------------------- | --------------------------------- |
| **Project name**        | 프로젝트 이름 (예: `growspace-test`)     |
| **MQTT Broker**         | Mosquitto 브로커가 설치된 PC의 IP 주소      |
| **Port**                | 기본값 `1883` 유지                     |
| **Client ID**           | 중복되지 않는 임의의 이름 (예: `testclient1`) |
| **Username / Password** | 브로커 설정에 따라 입력, 없다면 비워둠            |

> 같은 네트워크 내에서 접속하는 경우, IP 주소만 입력하면 연결이 가능합니다.\
> 외부 접속 시에는 공유기에서 1883 포트에 대한 **포트포워딩** 설정이 필요합니다.

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2FnfbppZWvEZMAKtt2JsMX%2Fimage.png?alt=media&amp;token=0403f697-f156-4318-8b57-38510e709253" alt=""><figcaption></figcaption></figure>

* 연결이 정상적으로 완료되면, 우측 상단 상태가 **CONNECT**로 변경됩니다.

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2FvCD3K8AEqcPLYsoYPBxv%2Fimage.png?alt=media&amp;token=9083d672-e77c-4606-b0db-b1f79cabf19f" alt=""><figcaption></figcaption></figure>

***

#### IP 주소 확인 방법 (Windows 기준)

* Windows 검색창에 `cmd` 입력 후, 명령 프롬프트 실행
  * `ipconfig` 명령어 입력 후 Enter

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2FmauDpr8tyBbVNmuPoJC3%2Fimage.png?alt=media&amp;token=87f20814-d955-40b2-88ad-4e4d7065ea61" alt="" width="563"><figcaption></figcaption></figure>

* 출력 결과 중 `IPv4 주소` 항목의 값을 확인\
  예: `192.168.0.101`

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2FZe5WdozSKJLB0QyaICZR%2Fimage.png?alt=media&amp;token=c1efb8a4-2d87-4fb3-bbc5-5a6d2c353d69" alt="" width="563"><figcaption></figcaption></figure>

* 이 주소가 MQTT Broker 항목에 입력할 IP입니다.

***

### 게이트웨이 데이터 구독 설정

Mosquitto 브로커와 연결된 후에는, MQTT-Studio에서 위치 데이터를 수신할 수 있도록 **Topic을 구독**합니다.

* 우측 상단의 **+ 버튼**을 클릭합니다.
* 아래 Topic 3개를 각각 입력하여 추가합니다.

| Topic                   | 설명                       |
| ----------------------- | ------------------------ |
| `uwb/gateway/start/#`   | 게이트웨이 부팅 시 상태 정보         |
| `uwb/gateway/config/#`  | 설정값, 측정 주기 등 게이트웨이 구성 정보 |
| `uwb/gateway/devices/#` | 태그 및 앵커의 실시간 위치 데이터      |

> `#` 기호는 해당 경로의 모든 하위 데이터를 포함해 구독합니다.\
> Topic 구조에 포함된 `projectId`는 GrowSpace 웹 설정 페이지에서 발급받은 API 키를 기준으로 구성됩니다.

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2FyFEf1l3jDktklbxkmki6%2Fimage.png?alt=media&amp;token=047a48e3-93ea-4626-82ae-a1e98e9a827d" alt=""><figcaption></figcaption></figure>

***

### 프로젝트 저장

토픽 등록이 완료되면, 좌측 상단 메뉴에서 **Save Project**를 클릭하여 설정을 저장합니다.\
이후에는 **Open Project**를 통해 동일한 설정으로 빠르게 다시 접속할 수 있습니다.

***

### 게이트웨이 설정 및 데이터 전송

GrowSpace 설정 웹페이지를 통해, 게이트웨이 Q1 장치가 **사설 Mosquitto 브로커로 데이터를 전송하도록 구성**할 수 있습니다.

#### 설정 절차

* 게이트웨이에 전원을 연결합니다.

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2FxkhAmtOIQnaZGIUS0szD%2Fimage.png?alt=media&amp;token=88c7b5ac-f2df-4852-8470-d0f73c921e11" alt=""><figcaption></figcaption></figure>

* Chrome 브라우저를 실행한 뒤, 아래 웹페이지에 접속합니다.\
  <https://uwb-gateway.web.app>
* 페이지 상단 메뉴에서 **게이트웨이 설정** 메뉴로 진입합니다.
* 아래 항목을 입력합니다.

| 항목                        | 설명                              |
| ------------------------- | ------------------------------- |
| **Wi-Fi Name / Password** | 2.4GHz Wi-Fi 정보 입력 (5GHz는 미지원)  |
| **MQTT IP**               | Mosquitto 브로커가 설치된 PC의 IP 주소 입력 |

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2F1QGK4m2lhmyErzk1KPtX%2Fimage.png?alt=media&amp;token=bb0489ba-c6fa-46ea-97df-5e0ae024096a" alt=""><figcaption></figcaption></figure>

* 모든 항목 입력 후 **저장** 버튼을 클릭하면, 게이트웨이가 자동으로 재시작됩니다.\
  이후 설정한 MQTT 브로커로 데이터를 전송하기 시작합니다.

***

### 5. MQTT-Studio에서 데이터 수신 확인

게이트웨이 설정이 완료되면, MQTT-Studio에서 실시간 위치 데이터가 자동으로 표시되기 시작합니다.\
아래는 실제 수신되는 메시지의 예시입니다.

```
Topic: uwb/gateway/devices/project-1234/TAG-001
{
  "tagId": "TAG-001",
  "x": 12.34,
  "y": 56.78,
  "z": 1.23,
  "timestamp": 1723850283
}
```

이 데이터를 통해 태그의 위치를 확인하거나, 실시간 모니터링 시스템에 연동할 수 있습니다.

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2F9LP4Hj4kU8bQqM106Dh4%2Fimage.png?alt=media&amp;token=92533138-56d9-4c59-8ca0-11a72aa984ab" alt=""><figcaption></figcaption></figure>