MQTT 클라이언트
외부 IIoT broker (HiveMQ / Mosquitto / EMQX / AWS IoT / Azure IoT Hub 등) 의 topic 을 게이트웨이가 클라이언트로 outbound 접속 해 subscribe / publish 합니다. 도착한 메시지는 in-memory 캐시에 저장되고, 태그의 수집 주기마다 캐시값을 읽어 갑니다.
| 상황 | 어떤 모드를 쓰나요 |
|---|---|
| 외부 IT 시스템이 REST POST 로 값을 보내올 때 | HTTP 푸시 |
| 외부 서버가 WebSocket 으로 push 할 때 | WebSocket 클라이언트 |
| 외부 IIoT MQTT broker 가 topic 으로 push 할 때 | MQTT 클라이언트 (이 페이지) |
| Sparkplug B 표준 (NBIRTH/DBIRTH/DCMD) | Sparkplug B |
| 사내 PLC 의 값을 직접 읽을 때 | Modbus / OPC-UA 등 |
등록 폼 입력값
| 입력 칸 | 무엇을 적나요 | 예시 |
|---|---|---|
| IP 주소 | MQTT broker 호스트 | broker.hivemq.com, 10.0.0.50 |
| 포트 | MQTT broker 포트 (평문 1883, TLS 8883) | 1883, 8883 |
| USERNAME | broker 인증 사용자명 (옵션) | iotuser |
| PASSWORD | broker 인증 비밀번호 (옵션) | s3cret |
| TLS | 평문 / TLS 선택 | false (tcp) / true (ssl) |
| QoS | subscribe / publish QoS | 0 / 1 / 2 |
| KEEP ALIVE | keep-alive 주기 (초) | 60 |
| CLEAN SESSION | clean session 플래그 | true (기본) / false |
| CLIENT ID | 명시 client id (옵션) | edge-plant-01 |
| 수집 주기 | 캐시된 값을 게이트웨이가 읽어가는 주기 (ms) | 1000 |
실제 broker URL: <scheme>://<host>:<port> (예: tcp://broker.hivemq.com:1883,
ssl://10.0.0.50:8883).
CLIENT ID 미지정 시 PP-<opc_id>-<random6> 형식으로 자동 생성됩니다 (MQTT v3.1 의
23자 권고 길이 안에서).
태그의 PLC 주소 표기 — 4-mode JSON
태그의 PLC 주소 = MQTT topic + 4-mode JSON 디코더. WebSocket / Apache Kafka 와 동일한 spec 입니다.
| 모드 | 형식 | 동작 |
|---|---|---|
| SCALAR | factory/line1/temp 또는 factory/line1/temp.value | 메시지 전체를 String 으로. 메시지가 JSON object 면 raw 폴백. |
| KEY | sensors/multi:temperature | top-level JSON key 의 값 (예: {"temperature":25.3,"humidity":60} → 25.3) |
| PATH | sensors/multi:$.data.tags.T1 | JSON Pointer 동적 evaluate (중첩 key 지원) |
| RAW | sensors/multi:_raw_ | 마지막 메시지 전체 (디버깅) |
Wildcard subscribe 도 지원:
| 태그의 PLC 주소 | 의미 |
|---|---|
device/+/status | 한 단계 wildcard (sensor01/sensor02/... 모두) |
factory/# | 멀티 wildcard (factory 하위 전체 — 마지막 도착 메시지 우선) |
read 의 첫 호출은 lazy subscribe (빈 문자열 반환). 다음 polling cycle 부터 캐시값이 들어옵니다.
자주 쓰는 사례
| 사례 | 어떻게 |
|---|---|
| HiveMQ Cloud / public broker | host = broker.hivemq.com 1883 (평문), 8883 (TLS+인증) |
| 사내 Mosquitto / EMQX | host = 사내 IP, 1883 / 8883. username/password 등록 |
| AWS IoT Core | host = <account>-ats.iot.<region>.amazonaws.com, 8883 + X.509 (별도 truststore 설정) |
| Azure IoT Hub | host = <hub>.azure-devices.net, 8883 + SAS 토큰 (username/password) |
| QoS=1 보장 | QoS=1 선택 — broker 가 ack 까지 재전송. 처리 비용 ↑ |
| 영구 세션 | CLEAN SESSION=false + 고정 CLIENT ID — broker 가 미수신 메시지 보관 |
write (publish)
태그 페이지 또는 REST API 로 값을 쓰면 broker 의 해당 topic 으로 즉시 publish 됩니다 (retain=false). value 의 String 이 그대로 payload 로 전송됩니다 — JSON / 평문 모두 가능.
plc_address = factory/line1/cmd
value = ON
→ MQTT publish: topic="factory/line1/cmd" payload="ON"
plc_address = devices/dev01/setpoint
value = {"sp":42.5,"unit":"degC"}
→ MQTT publish: topic="devices/dev01/setpoint" payload='{"sp":42.5,"unit":"degC"}'
흔한 문제와 해결
| 증상 | 원인 | 해결 |
|---|---|---|
| 값이 안 들어옴 | broker 가 메시지 publish 안 함 | mosquitto_sub -h <host> -p 1883 -t '<topic>' -v 로 직접 받아보고 줄이 나오는지 확인 |
[MQTT] connect 실패: not authorized | username/password 오류 | broker 사용자/패스워드 재확인. ACL 제한 확인 |
[MQTT] connect 실패: timeout | 방화벽 / 포트 막힘 | telnet <host> 1883, openssl s_client -connect <host>:8883 으로 검증 |
| TLS 핸드쉐이크 실패 | 자체서명 / cacerts 누락 | 운영에서는 정식 인증서 사용 권장. 임시 시 시스템 관리자에게 truststore 추가 요청 |
| Wildcard 가 한 번씩만 들어옴 | wildcard 는 마지막 도착 메시지 우선 | 토픽별로 분리해 등록 (각 토픽마다 별도 태그) |
더 자세한 기술 문서
- 고급 — 드라이버: MQTT 클라이언트
- Sparkplug B (MQTT + 표준 NBIRTH/DBIRTH/DCMD 페이로드)
- Eclipse Paho 공식 문서