자료실 유틸

MQTTX 1.13.0 ZIP 다운로드 및 사용법 (MQTT·ESP32 데이터 테스트)

조회 5

첨부파일 2

MQTTX는 MQTT 서버에 연결해 토픽을 구독하고 메시지를 발행하는 테스트 프로그램입니다. ESP32 센서 데이터, IoT 장치의 상태 메시지와 제어 명령을 확인할 때 사용할 수 있습니다.

MQTTX 1.13.0 공식 Windows x64 ZIP과 한국어 사용법·JSON 예제 ZIP을 첨부했습니다. MQTTX는 클라이언트이므로 메시지를 중계할 MQTT 브로커가 별도로 필요합니다.

1. 다운로드 및 실행

  • MQTTX-1.13.0-x64-win.zip: 공식 Windows 64비트 실행용 ZIP, 약 141.5 MiB. 모두 압축을 풀고 MQTTX.exe를 실행합니다. 함께 있는 resources 폴더와 DLL을 유지합니다.
  • MQTTX-guide-ko.zip: 한국어 사용법, 센서 데이터 JSON, 토픽 설정 예시, MQTTX의 Apache 2.0 라이선스 원문입니다.

설치형 파일과 macOS·Linux 배포본은 공식 다운로드에서 확인하세요. 첨부 파일의 기준 버전은 1.13.0 릴리스입니다.

2. MQTT 서버에 연결

실습용 브로커를 준비하거나 관리자가 제공한 브로커 접속 정보를 사용합니다. 로컬 PC에 브로커를 실행한 경우에만 Host를 127.0.0.1로 지정합니다.

  1. 새 연결을 만들고 Name에 IoT 실습처럼 알아보기 쉬운 이름을 입력합니다.
  2. Host에 브로커 주소, Port에 서비스 포트를 입력합니다. 일반 MQTT는 보통 1883, TLS 연결은 보통 8883을 사용하지만 실제 서버 설정을 우선합니다.
  3. Client ID는 브로커에 연결된 다른 클라이언트와 겹치지 않게 지정합니다. 예: jay-pc-demo-01
  4. 서버가 요구하는 Username·Password를 입력합니다. TLS 서버라면 SSL/TLS와 CA 인증서 등 서버가 지정한 항목도 설정합니다.
  5. MQTT 버전을 브로커에 맞추고 Connect를 눌러 연결 상태를 확인합니다.

접속 방식과 TLS 설정은 공식 시작 안내를 참고하세요. 브로커 계정과 비밀번호는 사용법 예제 ZIP에 넣지 않았습니다.

3. 토픽 구독 후 JSON 메시지 발행

연결이 완료되면 아래 토픽으로 구독과 발행을 시험합니다. Topic은 대소문자와 슬래시 위치까지 일치해야 합니다.

jay/demo/device01/telemetry
  1. New Subscription으로 위 토픽을 추가합니다. 첫 시험은 QoS 0으로 시작합니다.
  2. 발행 영역에도 같은 토픽을 입력하고 Payload 형식을 JSON으로 선택합니다.
  3. 아래 JSON을 붙여 넣습니다. QoS는 0, Retain은 끔으로 두고 전송 버튼을 누릅니다.
  4. 송신 기록과 함께 구독한 메시지가 수신되는지 확인합니다. MQTT 5 구독 옵션의 No Local을 켜면 자신이 보낸 메시지가 돌아오지 않으므로 이 실습에서는 끕니다.
{
  "device_id": "device01",
  "temperature_c": 24.5,
  "humidity_percent": 48.2,
  "status": "ok"
}

첨부 사용법 ZIP의 sensor-example.json에도 같은 데이터가 들어 있습니다. 실제 센서 측정값이 아닌 실습용 가상 값입니다.

4. ESP32와 메시지 주고받기

용도토픽 예시동작
센서 데이터jay/demo/device01/telemetryESP32가 발행, MQTTX가 구독
명령jay/demo/device01/commandMQTTX가 발행, ESP32가 구독
처리 결과jay/demo/device01/statusESP32가 발행, MQTTX가 구독

ESP32와 MQTTX가 같은 브로커를 사용하도록 설정하되 Client ID는 서로 다르게 지정합니다. MQTTX에서 아래 명령 예시를 보내려면 ESP32 펌웨어에 이를 해석하는 처리가 구현되어 있어야 합니다.

{"command":"led","value":1}

여러 장치의 센서 메시지는 jay/demo/+/telemetry로 구독할 수 있습니다. +는 한 단계, #는 여러 단계를 포함하는 구독용 와일드카드입니다. 발행할 때는 와일드카드 없는 실제 토픽을 입력합니다.

명령을 한 번 실행하는 시험에서는 Retain을 끄세요. Retain을 켜면 브로커에 보관된 명령이 나중에 접속한 구독자에게 전달될 수 있습니다. 토픽과 메시지 동작은 1.13.0 사용 설명을 참고하세요.

5. 자주 발생하는 문제

  • 연결 거부·시간 초과: 브로커 실행 상태, 주소·포트, 방화벽, VPN 필요 여부를 확인합니다. MQTTX만 실행해도 브로커가 생성되는 것은 아닙니다.
  • 연결과 끊김이 반복: 다른 PC나 장치와 Client ID가 중복되는지 확인합니다.
  • 연결은 되지만 메시지가 없음: 구독을 먼저 했는지, 토픽의 대소문자·경로, 계정의 발행·구독 권한과 No Local 설정을 확인합니다.
  • TLS 인증 실패: 접속 도메인, PC 시간, CA·클라이언트 인증서 요구사항을 확인합니다. 인증서 검증을 끄는 것으로 해결하지 말고 서버 설정에 맞춥니다.
  • 예전 데이터가 즉시 수신: 브로커에 남아 있는 retained 메시지인지 확인합니다.
  • 같은 메시지가 중복 수신: QoS 1은 중복 전달 가능성이 있으므로 실제 장치에서는 메시지 ID 등으로 중복 처리를 고려합니다.

6. 파일 검증 및 공식 자료

실행용 ZIP은 공식 원본을 그대로 첨부했고, SHA-256을 공식 릴리스 자산 값과 대조했습니다. 동봉 Electron·Chromium 고지도 유지했습니다.

10754f84217811db5048943541ffea421f34f14714b39e9b7b39241b039d3e95
Get-FileHash .\MQTTX-1.13.0-x64-win.zip -Algorithm SHA256

자료 확인일: 2026년 9월 12일. 토픽·Client ID와 JSON은 실습용 예시입니다.

목록으로

처리 중입니다...

잠시만 기다려주세요.