MQTT 장치나 서버가 메시지를 제대로 주고받는지 확인하려면 MQTTX에서 연결을 하나 만들고 같은 토픽을 구독한 뒤 시험 메시지를 보내면 됩니다. MQTTX는 Windows에서 사용할 수 있는 무료 오픈소스 MQTT 클라이언트입니다. 공식 GitHub 릴리스의 Windows 64비트 설치 파일은 MQTTX-Setup-1.13.1-x64.exe입니다.
시작하기 전에 접속할 MQTT 브로커의 주소와 포트를 준비하세요. MQTTX는 브로커에 연결해 메시지를 시험하는 프로그램이며, 설치만으로 브로커가 만들어지지는 않습니다. 처음이라면 자신이 관리하는 시험용 브로커의 접속 정보를 받아 두는 편이 좋습니다.
MQTTX로 무엇을 확인할 수 있나요?
MQTTX에서는 연결 상태를 보고, 토픽을 구독하고, 페이로드를 발행한 뒤 들어온 메시지를 한 화면에서 비교할 수 있습니다. 기기가 보냈다고 하는 값이 실제로 브로커를 거쳐 도착했는지 확인할 때 유용합니다. 공식 설명서는 MQTT 3.1.1과 5.0, TCP와 WebSocket 연결, 여러 페이로드 표시 형식을 안내합니다.
여기서는 가장 단순한 왕복 테스트를 합니다. 이미 접속 권한이 있는 브로커를 이용해 test/device/status라는 시험 토픽을 구독하고 같은 토픽으로 hello를 보냅니다. 업무용 브로커라면 실제 장치가 사용하는 토픽과 충돌하지 않는 시험 이름을 먼저 정하세요.
제작자 설명서에서 보는 MQTTX 연결과 메시지 화면
제작자 공식 설명서의 이전 macOS 화면입니다. 새 연결·구독·메시지 위치를 보여 주며, Windows용 1.13.1의 모양과 언어는 다를 수 있습니다.
| 프로그램 | MQTTX Desktop |
|---|---|
| 제작 | EMQ |
| Windows 설치 파일 | MQTTX-Setup-1.13.1-x64.exe |
| 버전 | 1.13.1 |
| 비용 | 무료 (Apache License 2.0) |
| 지원 환경 | Windows 64비트 |
| 이번 작업 | MQTT 토픽 구독과 발행·수신 확인 |
Windows 설치 파일 고르기
공식 릴리스에는 데스크톱 앱, 압축 파일, CLI 파일이 함께 올라옵니다. Windows 64비트 PC에 설치해 화면으로 테스트하려면 이름에 Setup과 x64가 들어간 MQTTX-Setup-1.13.1-x64.exe를 고르세요. mqttx-cli는 명령줄용으로, 이 글의 화면 안내와 다릅니다.
공식 저장소의 Apache License 2.0 안내와 릴리스 파일을 기준으로 무료 배포를 확인했습니다. 유료 브로커 서비스의 요금은 별개이므로, 접속하려는 서비스의 계정 조건도 확인하세요.
- Windows 설정에서 시스템 종류가 64비트인지 확인합니다.
- 공식 v1.13.1 릴리스에서 MQTTX-Setup-1.13.1-x64.exe를 선택합니다.
- 저장된 파일 이름을 대조하고 Windows 설치 안내를 따라 진행합니다.
- MQTTX를 열어 새 연결 화면이 나타나는지 확인합니다.
브로커에 새 연결 만들기
MQTTX 왼쪽의 +를 누르거나 첫 화면의 New Connection을 선택합니다. 브로커를 운영하는 사람에게 받은 주소, 포트, 사용자 이름과 비밀번호가 있다면 이 화면에 입력하세요. 공식 사용 설명서에는 Host, Port, Client ID가 연결 설정의 기본 항목으로 나옵니다.
암호화된 접속은 mqtts:// 또는 wss://처럼 접속 방식이 달라질 수 있습니다. 프로토콜만 바꾸고 기존 포트를 그대로 두면 연결되지 않을 수 있으므로, 브로커가 제공한 두 값을 함께 확인하세요. 화면에 연결된 것으로 표시돼야 다음 구독 단계로 넘어갈 수 있습니다.
- 알아보기 쉬운 연결 이름을 입력합니다. 여러 환경을 쓴다면 개발 서버처럼 용도를 적어 두세요.
- Host에 브로커 주소를 넣고 실제 접속 포트와 프로토콜을 맞춥니다.
- 브로커가 인증을 요구하면 Username과 Password를 입력합니다.
- TLS를 쓰는 서버라면 접속 방식과 인증서 설정을 서버 안내에 맞춥니다.
- Connect를 눌러 연결 상태가 바뀌는지 확인합니다.
토픽을 구독하고 시험 메시지 보내기
연결 화면에서 New Subscription을 누르고 시험 토픽을 입력합니다. 토픽은 메시지가 오가는 주소처럼 생각하면 쉽습니다. 먼저 구독을 해 두어야 같은 토픽으로 보낸 메시지가 수신 목록에 나타나는지 확인할 수 있습니다.
공식 설명서는 구독한 토픽을 다시 발행 영역에 입력한 뒤 메시지를 보내면 발행과 수신을 한 화면에서 확인할 수 있다고 안내합니다. 먼저 평문 한 단어로 시험하면 JSON 형식 오류와 연결 문제를 구분하기 쉽습니다. 토픽 이름은 대소문자와 / 구분까지 같아야 합니다.
- New Subscription의 Topic에 예를 들어 test/device/status를 입력하고 Confirm을 누릅니다.
- 화면 아래 발행 영역의 토픽에도 정확히 같은 test/device/status를 입력합니다.
- Payload에 hello처럼 짧은 시험 문구를 적습니다.
- 전송 버튼을 누르고 메시지 목록에서 보낸 항목과 받은 항목을 확인합니다.
보냈는데 받은 메시지가 보이지 않는다면
먼저 화면 위의 연결 상태를 보세요. 연결이 끊겼다면 발행 버튼을 다시 누르기 전에 브로커 주소와 포트부터 확인해야 합니다. 연결 상태가 정상이라면 구독 목록의 토픽과 발행 영역의 토픽을 나란히 비교하세요.
메시지 목록에는 필터가 적용될 수 있습니다. 다른 토픽을 선택한 상태라면 방금 보낸 메시지가 숨겨졌을 수 있으니 All 보기를 확인하세요. 브로커의 권한 설정이 발행과 구독을 따로 제한하는 경우도 있으므로, 두 권한을 모두 받았는지 관리 담당자에게 확인하면 원인을 좁힐 수 있습니다.
연결 자체가 실패한다면 Host와 Port, 접속 방식, 계정 정보를 한 번에 바꾸지 말고 하나씩 대조하세요. 보낸 기록만 보인다면 구독 토픽과 발행 토픽의 철자를 먼저 비교합니다. 일부 메시지만 빠진다면 현재 선택한 구독 필터와 QoS를 살펴보고, JSON 입력에서 막힌다면 표시 형식을 Plaintext로 바꿔 짧은 문구부터 보내 보세요. 어떤 단계에서 멈추는지 확인해야 브로커 연결 문제와 메시지 형식 문제를 구별할 수 있습니다.
시험 토픽과 공개 브로커를 사용할 때
공식 사용 설명서는 간단한 실습에 쓸 공개 브로커도 소개합니다. 공개 브로커는 여러 사람이 함께 쓰는 시험 공간이므로 비밀번호, 개인 정보, 실제 장치 데이터는 보내지 마세요. 자기 서비스의 연결 문제를 조사할 때는 해당 서비스가 지정한 브로커와 계정으로 다시 시험해야 합니다.
한 번 왕복에 성공했다면 실제 장치가 쓰는 토픽을 구독해 메시지가 들어오는지 살펴보세요. 반대로 장치로 명령을 보내려면 장치 문서에서 명령 토픽과 허용 페이로드를 먼저 확인해야 합니다. 예제 토픽이 모든 장치에서 통하는 것은 아닙니다.
보내는 쪽과 받는 쪽을 나눠 시험하기
한 연결에서 보낸 메시지를 같은 연결에서 받는 첫 테스트가 끝났다면, 연결을 두 개 만들어 실제 장치에 가까운 흐름도 확인할 수 있습니다. 공식 설명서에는 한 클라이언트가 토픽을 구독하고 다른 클라이언트가 같은 토픽으로 메시지를 발행하는 예시가 있습니다. 두 연결이 같은 브로커에 접속해야 결과를 비교할 수 있습니다.
이렇게 나눠 보면 한 연결의 자기 메시지만 본 것인지, 다른 클라이언트까지 전달됐는지 구별할 수 있습니다. 두 연결 모두 이름을 다르게 붙여 두면 화면을 오갈 때 헷갈리지 않습니다. 실제 장치의 오류를 조사할 때도 장치 대신 보내는 연결을 하나 만들어 비교하면 어느 쪽 설정부터 살펴볼지 판단하기 쉽습니다.
- 받는 쪽 연결을 만들고 시험 토픽을 구독합니다.
- 별도의 보내는 쪽 연결을 만들어 같은 브로커에 접속합니다.
- 보내는 쪽에서 구독한 토픽으로 짧은 메시지를 발행합니다.
- 받는 쪽 화면에 토픽과 내용이 나타나는지 확인합니다.
숫자나 JSON을 보낼 때는 형식도 맞추세요
처음에는 hello 같은 평문으로 연결을 검증하고, 그다음 장치가 쓰는 데이터 형식으로 바꿔 보세요. MQTTX의 발행 영역에서는 Plaintext, JSON, Hex, Base64 등 페이로드 표시 형식을 선택할 수 있습니다. 화면에서 JSON을 골랐다면 { "status": "on" }처럼 JSON 문법에 맞는 값을 입력해야 합니다.
메시지가 도착해도 장치나 서버가 값을 처리하지 못한다면, 연결 성공 여부와 데이터 형식 문제를 분리해 보세요. 토픽이 맞는지, 기대하는 키 이름이 같은지, 숫자를 문자로 보내지는 않았는지 장치 문서와 비교하면 됩니다. MQTTX의 발행 성공 표시는 상대 프로그램이 그 내용을 원하는 방식으로 처리했다는 뜻까지 보증하지 않습니다.
테스트 뒤에는 임시 토픽과 연결 이름을 정리하세요. 다음에 같은 브로커를 열었을 때 test/device/status가 실제 장치 토픽으로 오해되지 않게 하는 편이 좋습니다. 문제가 다시 생겼다면 브로커 주소, 사용한 토픽, 보낸 짧은 예제 값을 기록해 두면 동일한 조건에서 다시 비교할 수 있습니다.
화면 사진과 현재 버전의 차이
아래 화면은 제작자의 공식 사용 설명서에 있는 MQTTX 실제 화면입니다. 새 연결 버튼, 구독 창, 메시지 목록의 위치를 보여 주지만 오래된 설명서의 macOS 화면이라 Windows용 1.13.1에서는 모양이나 언어가 다를 수 있습니다. 현재 릴리스는 한국어 표시를 지원합니다. 버튼 이름이 번역돼 있다면 같은 기능의 메뉴를 찾아 진행하세요.
사진에서 왼쪽 +는 연결 추가, New Subscription은 토픽 구독, 오른쪽 아래 입력 영역은 발행할 토픽과 페이로드를 쓰는 곳입니다. 화면을 그대로 외우기보다 연결 → 구독 → 발행 → 수신 확인 순서를 기억하면 됩니다.
자주 묻는 질문
MQTTX만 설치하면 메시지를 보낼 수 있나요?
브로커 주소와 접속 권한이 필요합니다. MQTTX는 브로커에 연결하는 클라이언트입니다.
Windows 64비트에서는 어떤 파일을 고르나요?
공식 v1.13.1 릴리스의 MQTTX-Setup-1.13.1-x64.exe입니다. CLI와 압축 파일은 구분해서 보세요.
무료인가요?
MQTTX 데스크톱 앱은 Apache License 2.0 오픈소스입니다. 접속하는 브로커 서비스의 이용 조건은 별도로 확인해야 합니다.
구독했는데 내 메시지가 안 보이는 이유는 무엇인가요?
연결 상태를 확인하고 구독·발행 토픽의 철자와 메시지 목록 필터를 비교하세요.
사진과 Windows 화면이 다른데 괜찮나요?
사진은 제작자 설명서의 이전 macOS 화면입니다. 최신 Windows 앱에서 버튼 위치나 번역은 달라질 수 있습니다.
먼저 짧은 문구로 한 번 왕복해 보세요
브로커에 연결했다면 시험 토픽을 구독하고 hello를 보내 보세요. 수신 목록에서 같은 문구를 확인한 뒤 실제 장치의 토픽과 데이터 형식으로 옮겨 가면 됩니다. 첫 테스트가 막히면 연결 상태와 두 토픽 이름부터 차례로 확인하세요.
공식 자료와 확인일
MQTTX 공식 저장소 · 공식 v1.13.1 릴리스 · 공식 사용 설명서 · 공식 라이선스 | 2026-10-08T17:45:23.988390+00:00
