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

# MQTT 서버 설치 및 환경 구축

Mosquitto로 위치 데이터 수신 테스트 환경 만들기

### 이 글에서는

GrowSpace 게이트웨이 Q1을 **사설 MQTT 브로커(Mosquitto)**와 연동하여 태그 및 앵커의 실시간 위치 데이터를 직접 수신하고, **MQTT-Studio를 통해 시각적으로 확인하는 방법**을 안내합니다.

기본적으로 게이트웨이는 프리그로우 서버와 연동되지만,\
**내부 테스트나 외부 시스템과의 연동이 필요한 경우** Mosquitto를 통해 손쉽게 환경을 구성할 수 있습니다.

***

### Mosquitto란?

Mosquitto는 MQTT(Message Queuing Telemetry Transport) 프로토콜을 기반으로 동작하는 오픈소스 메시지 브로커입니다.

MQTT는 IoT(사물인터넷) 환경에서 널리 사용되는 경량 통신 프로토콜로, 장치 간 실시간 메시지 송수신을 매우 효율적으로 처리할 수 있습니다.

Mosquitto는 다음과 같은 특징을 가집니다:

* 설치 및 설정이 간단하고 가볍습니다.
* 수백\~수천 개의 장치가 동시에 연결되어도 안정적으로 작동합니다.
* TCP/IP 기반으로 작동하며, 인증/암호화 설정도 가능합니다.

GrowSpace 게이트웨이 Q1은 기본적으로 MQTT 프로토콜을 사용해 데이터를 전송하기 때문에, Mosquitto를 사용하면 별도의 클라우드 없이도 자체 서버 환경에서 데이터를 수신하고 처리할 수 있습니다.

***

### Mosquitto 브로커 설치 및 설정

#### Mosquitto 설치

* [Mosquitto 공식 페이지](https://mosquitto.org/download/)에서 Windows 설치 파일 다운로드

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2FChBnUl04bNu7NxWWsHRL%2Fimage.png?alt=media&amp;token=8a4e7d92-0d4b-4131-80e9-74f75cb09d31" alt=""><figcaption></figcaption></figure>

* 설치 후, 기본 경로:

```
C:\Program Files\mosquitto
```

#### 설정 파일 수정하기

* 메모장 또는 VS Code로 아래 경로의 설정 파일을 엽니다:

```
C:\Program Files\mosquitto\mosquitto.conf
```

* 아래 두 항목을 각각 **해당 위치 아래에 추가**해 주세요:
  * `#listener` 항목을 검색한 뒤, 그 아래에 다음 줄을 추가합니다:

    ```
    listener 1883 0.0.0.0
    ```
  * `#allow_anonymous` 항목을 검색한 뒤, 그 아래에 다음 줄을 추가합니다:

    ```
    allow_anonymous true
    ```

> 🔸 `listener` 항목은 외부 장비의 접속을 허용하는 포트를 지정합니다.\
> 🔸 `allow_anonymous true`는 사용자 인증 없이도 접속할 수 있도록 허용하는 설정입니다.

{% hint style="info" %}
기존의 `#listener`, `#allow_anonymous false`는 그대로 **주석(#)** 처리된 상태로 남겨둡니다.\
실제로 적용되는 설정은 새로 추가한 두 줄입니다.
{% endhint %}

* 저장 후 Mosquitto를 재시작하거나 PC를 재부팅해 주세요.

이 설정을 통해 외부 장비(GrowSpace 게이트웨이 등)에서도 Mosquitto 브로커에 접속할 수 있게 됩니다.

### Windows 방화벽에서 포트 열기

Mosquitto 브로커가 외부 장치(GrowSpace 게이트웨이 등)와 통신하려면 TCP 1883 포트를 방화벽에서 허용해야 합니다.

다음 절차를 통해 인바운드 규칙을 추가해 주세요.

#### 방화벽 규칙 추가 방법

{% stepper %}
{% step %}
**시작 버튼 클릭** → `방화벽` 입력 → **Windows Defender 방화벽** 실행

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2FMOM8Ru4mrnnk47wHz3Nv%2Fimage.png?alt=media&amp;token=e3b88932-3266-4705-bdb4-37bd69344009" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
왼쪽 메뉴에서 **고급 설정** 선택

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2F73yyxvhFaqF64wbtvQF0%2Fimage.png?alt=media&amp;token=de23357c-4f32-49c7-a740-f85a1650cc00" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
왼쪽 메뉴에서 **인바운드 규칙** 클릭 → 오른쪽에서 **새 규칙** 선택

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2FVi9q8dJezE383uwyutHi%2Fimage.png?alt=media&amp;token=a6bd78c5-67dc-4785-9fba-de2c10d45025" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**규칙 종류**는 `포트` 선택 → 다음

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2FN5Qckn01sHB8Slpe1M1y%2Fimage.png?alt=media&amp;token=e0eb27fa-36bf-473a-8a72-08af7c644249" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**프로토콜 및 포트**

&#x20;   프로토콜: `TCP`\
&#x20;   특정 로컬 포트: `1883` → 다음

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2FonCILJEz5wShr1eYqN9P%2Fimage.png?alt=media&amp;token=ba2ba8b4-387d-47af-a434-14b48a7dfaf0" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**작업 설정**

`연결 허용` 선택 → 다음

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2Ffd7KcW9p6laY5lGkl1AU%2Fimage.png?alt=media&amp;token=bd72ad5e-a576-4be8-9da8-31281f670705" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**프로필 설정**

도메인 / 개인 / 공용 **모두 체크** → 다음

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2FGcyAb3NO5CaG6VY0Og7O%2Fimage.png?alt=media&amp;token=2d53295f-55f0-4ba8-a2ee-2f5a59a2ba28" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**이름 지정**

`Mosquitto MQTT 허용` → 완료

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2FOyitfQJYW9xyHMiNIcsh%2Fimage.png?alt=media&amp;token=37b8c986-b578-4e81-84ff-a09106d21a57" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
설정이 완료되면 **컴퓨터를 재시작**하여 적용합니다.
{% endstep %}
{% endstepper %}

> 포트가 제대로 열리지 않으면 게이트웨이에서 MQTT 브로커로 데이터를 전송할 수 없습니다.\
> 테스트 중 연결이 되지 않는 경우, 방화벽 설정을 다시 확인해 주세요.

***

### MQTT-Studio 설치 및 브로커 접속

#### 왜 이 도구가 필요할까요?

`MQTT-Studio`는 Mosquitto 브로커에 접속해 **위치 데이터가 제대로 전송되고 있는지 실시간으로 확인**할 수 있는 시각화 도구입니다.

* 게이트웨이에서 전송된 MQTT 메시지를 바로 확인 가능
* Start, Config, Devices 데이터를 토픽별로 구분해서 보기 쉬움
* 개발/디버깅/시연에 유용

### 설치 방법

{% stepper %}
{% step %}
Windows 작업 표시줄에서 **Microsoft Store** 실행

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2F15Z8U51OCXnp6XMKX9wT%2Fimage.png?alt=media&amp;token=88c6ce18-c459-423f-b013-f23f276f7fb4" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

{% step %}
상단 검색창에 `"MQTT-Studio"` 입력

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2F9hAtg9EbbXW5Ui9klAm1%2Fimage.png?alt=media&amp;token=31eecd9c-2f9a-416a-9a6e-68bf2a1a1006" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

{% step %}
목록에서 MQTT-Studio 선택 후 **\[설치]** 클릭&#x20;
{% endstep %}

{% step %}
설치 완료 후 프로그램 실행
{% endstep %}
{% endstepper %}

#### 브로커 연결 설정

MQTT-Studio를 실행한 뒤, 좌측 메뉴에서 **\[New Project]** 버튼을 클릭합니다.\
아래 항목들을 입력합니다:

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2F0EVI72E40yAq8tekvqTY%2Fimage.png?alt=media&amp;token=9b30124d-cc21-4fa3-b729-ca27331b3efe" alt=""><figcaption></figcaption></figure>

| 항목                  | 설명                                                                  |
| ------------------- | ------------------------------------------------------------------- |
| Project name        | 원하는 이름 입력 (예: `growspace-test`)                                     |
| MQTT Broker         | Mosquitto가 설치된 PC의 **IP 주소**(Windows CMD → `ipconfig` → IPv4 주소 확인) |
| Port                | `1883` (기본값 유지)                                                     |
| Client ID           | 중복되지 않는 임의의 ID (예: `testclient1`)                                   |
| Username / Password | 별도 설정이 없다면 비워둬도 됩니다                                                 |

**같은 공유기(내부 네트워크)** 환경에서는 IP 주소만 입력하면 바로 연결됩니다.\
**외부 네트워크(인터넷)** 에서 접속하려면, 브로커가 설치된 PC의 공유기에서\
포트 포워딩 설정이 필요합니다: `TCP 1883 → 내부 IP` 로 포워딩 설정

#### 연결 확인

모든 항목을 입력한 후 **\[Connect]** 버튼을 클릭합니다.\
연결이 성공하면 **화면 상단에 CONNECT 버튼이 활성화**됩니다.

<figure><img src="https://2885569511-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYKyrLLe7cm7ZOhiSB0gg%2Fuploads%2FapBmh9KkBp2TZlunv5sy%2Fimage.png?alt=media&amp;token=3b9feae6-7db4-4a32-ac2e-75ff5c1e31ae" alt=""><figcaption></figcaption></figure>

***

### 환경 구축 완료

지금까지 Mosquitto 브로커를 설치하고, 포트 설정 및 MQTT-Studio를 통한 데이터 시각화까지 완료했습니다. 이 과정을 통해 GrowSpace 게이트웨이 Q1에서 수집한 UWB 위치 데이터를 자체 브로커로 수신할 수 있는 환경이 구성되었습니다.

이제 다음 단계에서는 게이트웨이 장치를 설정하고, 실제로 위치 데이터를 송신하는 과정을 이어서 진행하시면 됩니다.