목차
들어가며
현대의 IoT(Internet of Things) 환경에서는 수많은 디바이스가 서로 통신하며 데이터를 주고받는다. 이러한 통신을 효율적으로 처리하기 위해서는 경량화되고 안정적인 메시징 프로토콜이 필요하다. Eclipse Mosquitto는 이러한 요구사항을 충족하는 대표적인 MQTT 브로커이다.
MQTT 프로토콜의 이해
MQTT(Message Queuing Telemetry Transport)는 IBM에서 개발한 경량 메시징 프로토콜이다. 이 프로토콜은 네트워크 대역폭이 제한적이거나 불안정한 환경에서도 안정적인 메시지 전송을 보장한다. 특히 배터리로 동작하는 IoT 디바이스나 모바일 애플리케이션에 최적화되어 있다.
MQTT의 핵심 특징은 다음과 같다:
- 경량성: TCP/IP 위에서 동작하며 최소한의 오버헤드만을 가진다
- 비동기 통신: Publisher와 Subscriber가 직접 연결되지 않고 브로커를 통해 통신한다
- QoS 지원: 메시지 전달 보장 수준을 3단계로 제어할 수 있다
Eclipse Mosquitto 소개
Eclipse Mosquitto는 Eclipse Foundation에서 관리하는 오픈소스 MQTT 브로커이다. C언어로 작성되어 높은 성능과 안정성을 제공하며, 다양한 플랫폼에서 동작한다.
주요 특징
1. 높은 성능
- 수천 개의 동시 연결 처리 가능
- 낮은 메모리 사용량 (약 3MB 이하)
- 빠른 메시지 처리 속도
2. 표준 준수
- MQTT v3.1, v3.1.1, v5.0 프로토콜 완전 지원
- OASIS 표준 완전 호환
3. 보안 기능
- TLS/SSL 암호화 지원
- 사용자 인증 및 권한 관리
- ACL(Access Control List) 지원
4. 확장성
- 플러그인 아키텍처 지원
- 브리지 기능으로 다른 브로커와 연동 가능
MQTT 통신 패턴
MQTT는 Publisher-Subscriber 패턴을 기반으로 한다. 이 패턴에서는 다음과 같은 역할이 존재한다:
- Publisher: 메시지를 특정 토픽으로 발행하는 클라이언트
- Subscriber: 특정 토픽을 구독하여 메시지를 수신하는 클라이언트
- Broker: Publisher와 Subscriber 사이에서 메시지를 중계하는 서버
토픽은 계층 구조로 구성되며, 슬래시(/)로 구분한다. 예를 들어 building/floor1/room101/temperature와 같은 형태이다.
우분투 서버에서 Mosquitto 설치 및 구성
설치 과정
# 패키지 목록 업데이트
sudo apt update
# Mosquitto 브로커와 클라이언트 도구 설치
sudo apt install mosquitto mosquitto-clients
# 서비스 자동 시작 설정
sudo systemctl enable mosquitto
# 서비스 시작
sudo systemctl start mosquitto
# 설치 상태 확인
sudo systemctl status mosquitto
위 명령어들은 다음과 같은 작업을 수행한다:
- apt update: 시스템의 패키지 목록을 최신 상태로 업데이트한다
- apt install mosquitto mosquitto-clients: Mosquitto 브로커와 테스트용 클라이언트 도구를 설치한다
- systemctl enable mosquitto: 시스템 부팅 시 자동으로 Mosquitto 서비스가 시작되도록 설정한다
- systemctl start mosquitto: Mosquitto 서비스를 즉시 시작한다
- systemctl status mosquitto: 서비스 실행 상태를 확인한다
기본 설정
Mosquitto의 주 설정 파일은 /etc/mosquitto/mosquitto.conf에 위치한다. 기본 설정에서는 포트 1883에서 비암호화 연결을 허용한다.
# 설정 파일 편집
sudo vi /etc/mosquitto/mosquitto.conf
# 서비스 재시작으로 설정 적용
sudo systemctl restart mosquitto기본 사용법 및 테스트
메시지 구독
# localhost의 기본 포트(1883)에서 "test/topic" 토픽 구독
mosquitto_sub -h localhost -t "test/topic"
# 모든 센서 관련 토픽 구독 (와일드카드 사용)
mosquitto_sub -h localhost -t "sensors/+"
# 모든 토픽 구독
mosquitto_sub -h localhost -t "#"mosquitto_sub은 토픽 구독 동작을 무한히 수행하며, 각 옵션의 의미는 다음과 같다:
- -h localhost: 브로커 호스트 주소 (기본값: localhost)
- -t "topic": 구독할 토픽 이름
- +: 단일 레벨 와일드카드 (예: sensors/+ → sensors/temperature, sensors/humidity)
- #: 다중 레벨 와일드카드 (예: sensors/# → sensors/room1/temperature, sensors/room2/humidity/current)
메시지 발행
# 단순 텍스트 메시지 발행
mosquitto_pub -h localhost -t "test/topic" -m "Hello MQTT!"
# JSON 형태의 센서 데이터 발행
mosquitto_pub -h localhost -t "sensors/temperature" -m '{"value": 23.5, "unit": "celsius", "timestamp": "2025-05-22T10:30:00Z"}'
# QoS 레벨 2로 중요한 메시지 발행
mosquitto_pub -h localhost -t "alerts/fire" -m "Fire detected in Building A" -q 2mosquitto_pub은 메시지 발행 동작이므로 1회성으로 수행하며, 각 옵션의 의미는 다음과 같다:
- -m "message": 발행할 메시지 내용
- -q 2: QoS(Quality of Service) 레벨 설정 (0: 최대 1회, 1: 최소 1회, 2: 정확히 1회)
FastAPI와 함께 사용하기
FastAPI에서 Eclipse Mosquitto MQTT 브로커를 사용하기 위해서, fastapi-mqtt 라이브러리를 활용하여 FastAPI 애플리케이션과 MQTT 브로커 간의 통신을 설정할 수 있다. fastapi-mqtt는 Mosquitto와 같은 다양한 MQTT 브로커와 연동할 수 있는 FastAPI용 MQTT 클라이언트 래퍼로서, paho-mqtt 기반의 비동기 MQTT 클라이언트를 래핑한다.
1. Mosquitto 브로커 실행
Docker를 사용하여 로컬에서 Mosquitto 브로커를 실행할 수 있다.
docker run -d --name mosquitto -p 1883:1883 eclipse-mosquitto2. FastAPI와 MQTT 설정
fastapi-mqtt를 설치하고 FastAPI 애플리케이션에 통합한다:
pip install fastapi uvicorn fastapi-mqtt다음은 FastAPI 애플리케이션에서 MQTT를 설정하는 예제이다:
from fastapi import FastAPI
from fastapi_mqtt import FastMQTT, MQTTConfig
app = FastAPI()
mqtt_config = MQTTConfig(
host="localhost", # MQTT 브로커 호스트
port=1883, # MQTT 브로커 포트
keepalive=60,
username="", # 필요 시 사용자명
password="" # 필요 시 비밀번호
)
mqtt = FastMQTT(config=mqtt_config)
mqtt.init_app(app)
@app.on_event("startup")
async def startup():
print("FastAPI 애플리케이션이 시작되었습니다.")
@mqtt.on_connect()
def connect(client, flags, rc, properties):
print("MQTT 브로커에 연결되었습니다.")
mqtt.client.subscribe("test/topic") # 구독할 토픽
@mqtt.on_message()
async def message(client, topic, payload, qos, properties):
print(f"수신된 메시지: {payload.decode()}")
@app.post("/publish")
async def publish_message():
mqtt.publish("test/topic", "Hello from FastAPI!")
return {"message": "메시지를 발행했습니다."}이 예제에서는 FastAPI 애플리케이션이 시작될 때 MQTT 브로커에 연결하고, 특정 토픽을 구독하며, /publish 엔드포인트를 통해 메시지를 발행한다.
3. 애플리케이션 실행
uvicorn main:app --host 0.0.0.0 --port 8000 --reload이제 브라우저에서 http://localhost:8000/docs에 접속하여 Swagger UI를 통해 /publish 엔드포인트를 테스트할 수 있다.
4. MQTT 메시지 수신 확인
다른 MQTT 클라이언트를 사용하여 test/topic 토픽을 구독하면, FastAPI 애플리케이션에서 발행한 메시지를 실시간으로 확인할 수 있다.
실제 활용 사례
IoT 센서 모니터링 시스템
스마트 빌딩에서 온도, 습도, 조도 센서들이 정기적으로 데이터를 전송하는 시스템을 구축할 수 있다:
# 온도 센서 데이터 시뮬레이션
mosquitto_pub -h localhost -t "building/floor1/room101/temperature" \
-m '{"value": 23.5, "unit": "celsius", "timestamp": "2025-05-22T10:30:00Z"}'
# 습도 센서 데이터 시뮬레이션
mosquitto_pub -h localhost -t "building/floor1/room101/humidity" \
-m '{"value": 45.2, "unit": "percent", "timestamp": "2025-05-22T10:30:00Z"}'
실시간 알림 시스템
위험 상황 발생 시 즉시 알림을 전송하는 시스템:
# 화재 경보 시뮬레이션 (QoS 2로 확실한 전달 보장)
mosquitto_pub -h localhost -t "alerts/fire" \
-m '{"level": "critical", "location": "Building A, Floor 2", "timestamp": "2025-05-22T10:35:00Z"}' \
-q 2
원격 기기 제어
IoT 기기를 원격으로 제어하는 명령을 전송:
# LED 제어 명령
mosquitto_pub -h localhost -t "devices/led/control" \
-m '{"action": "turn_on", "brightness": 80, "color": "blue"}'
# 에어컨 제어 명령
mosquitto_pub -h localhost -t "devices/aircon/control" \
-m '{"action": "set_temperature", "target": 22, "mode": "cooling"}'
보안 설정
프로덕션 환경에서는 반드시 보안 설정을 적용해야 한다.
사용자 인증 설정
# 패스워드 파일 생성
sudo mosquitto_passwd -c /etc/mosquitto/passwd username
# 추가 사용자 등록
sudo mosquitto_passwd /etc/mosquitto/passwd another_user
설정 파일 수정
# /etc/mosquitto/mosquitto.conf
allow_anonymous false
password_file /etc/mosquitto/passwd
# TLS 설정 (인증서가 있는 경우)
listener 8883
cafile /etc/mosquitto/ca_certificates/ca.crt
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
성능 최적화 및 모니터링
로그 설정
# /etc/mosquitto/mosquitto.conf
log_dest file /var/log/mosquitto/mosquitto.log
log_type error
log_type warning
log_type notice
log_type information
log_timestamp true
연결 제한 설정
# 최대 동시 연결 수 제한
max_connections 1000
# 메시지 큐 크기 제한
max_queued_messages 100
# 메시지 크기 제한 (바이트)
message_size_limit 8192
결론
Eclipse Mosquitto는 안정적이고 효율적인 MQTT 브로커로서 IoT 시스템 구축에 필수적인 도구이다. FastAPI와의 연동을 통해 현대적인 웹 API 기반의 IoT 플랫폼을 구축할 수 있으며, MongoDB와 함께 사용하면 센서 데이터의 영구 저장 및 분석도 가능하다.
특히 우분투 서버 환경에서 nginx와 함께 운용하면 확장 가능하고 안전한 IoT 인프라를 구성할 수 있다. 초기 설정은 간단하지만, 프로덕션 환경에서는 보안 설정과 성능 튜닝을 반드시 적용해야 한다는 점을 명심해야 한다.