· Colinch NAS · 5 min read
Zigbee2MQTT 설정 완전 가이드 — 별도 허브 없이 Zigbee 기기 연결하는 법
Zigbee2MQTT와 SONOFF Zigbee 3.0 USB 동글로 Zigbee 기기를 Home Assistant에 직접 연결하는 방법. Mosquitto MQTT 브로커 설정부터 기기 페어링까지.
Zigbee 기기를 쓰려면 보통 삼성 SmartThings 허브, Philips Hue 허브 같은 전용 허브가 필요하다. Zigbee2MQTT는 USB 동글 하나로 이 허브들을 대체한다. 클라우드 연동도 없고, 모든 데이터가 집 안에서만 돌아간다.
이전 글에서 Home Assistant 설치 방법을 다뤘다. Home Assistant가 준비돼 있어야 이 글이 의미 있다.
환경 정보
| 항목 | 버전/모델 |
|---|---|
| Home Assistant | 2026.5.x (HAOS) |
| Zigbee 동글 | SONOFF Zigbee 3.0 USB Dongle Plus (CC2652P) |
| Zigbee2MQTT | 1.38.x |
| Mosquitto MQTT | 2.0.x |
필요한 것
- Zigbee USB 동글: SONOFF Zigbee 3.0 USB Dongle Plus 추천. 약 2만원. CC2652P 칩셋 기반이라 Zigbee2MQTT 공식 지원.
- Mosquitto MQTT 브로커: Zigbee2MQTT가 MQTT 브로커를 통해 Home Assistant와 통신.
1단계: Mosquitto MQTT 브로커 설치
HAOS 환경이라면 Settings → Add-ons → Add-on Store에서 Mosquitto broker를 검색해서 설치한다.
설치 후 Configuration 탭에서 아래 설정 추가:
logins:
- username: mqtt_user
password: mqtt_password
저장하고 시작. MQTT 브로커가 1883 포트에서 대기한다.
Docker 환경이라면:
# docker-compose.yml
services:
mosquitto:
image: eclipse-mosquitto:2
container_name: mosquitto
ports:
- "1883:1883"
- "9001:9001"
volumes:
- /volume1/docker/mosquitto/config:/mosquitto/config
- /volume1/docker/mosquitto/data:/mosquitto/data
- /volume1/docker/mosquitto/log:/mosquitto/log
restart: unless-stopped
# /volume1/docker/mosquitto/config/mosquitto.conf
listener 1883
allow_anonymous false
password_file /mosquitto/config/passwords
# 패스워드 파일 생성
sudo docker exec -it mosquitto mosquitto_passwd -c /mosquitto/config/passwords mqtt_user
2단계: Zigbee USB 동글 연결
USB 동글을 서버(Raspberry Pi 또는 미니PC)에 꽂는다. HAOS에서는 자동으로 인식한다.
동글의 장치 경로 확인:
# SSH에서 실행
ls -la /dev/serial/by-id/
# 출력 예: usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_...
3단계: Zigbee2MQTT 설치
HAOS에서는 Add-on Store에서 Zigbee2MQTT 검색 설치. 설치 후 Configuration 탭에서 설정:
mqtt:
server: mqtt://localhost:1883
user: mqtt_user
password: mqtt_password
serial:
port: /dev/ttyACM0 # 동글 경로
frontend:
port: 8099
homeassistant: true
serial.port는 위에서 확인한 장치 경로로 설정. 동글마다 경로가 다르다.
시작 후 http://homeassistant-ip:8099에서 Zigbee2MQTT 웹 UI에 접속할 수 있다.
4단계: Zigbee 기기 페어링
Zigbee2MQTT 웹 UI 상단에서 페어링 허용 (Permit join) 버튼 클릭.
Zigbee 기기 페어링 방법은 제품마다 다르다. 보통 리셋 버튼 길게 누르기 또는 전원 껐다 켜기를 반복하면 된다. 페어링되면 웹 UI의 기기 탭에 새 기기가 나타난다.
자동으로 Home Assistant에도 기기가 등록된다. 설정 → 기기 및 서비스 → MQTT에서 확인할 수 있다.
Home Assistant 연동
Zigbee2MQTT 기기가 자동으로 Home Assistant에 추가되려면 homeassistant: true 설정이 돼 있어야 한다(위 설정에 포함됨).
자동화 예시 — 모션 감지 시 조명 켜기:
# Home Assistant 자동화
alias: "모션 감지 시 거실 조명 켜기"
trigger:
- platform: state
entity_id: binary_sensor.motion_sensor_occupancy
to: "on"
action:
- service: light.turn_on
target:
entity_id: light.living_room
삽질했던 부분
동글 경로가 부팅마다 바뀜: /dev/ttyACM0으로 설정했는데 재부팅 후 /dev/ttyACM1로 바뀌어서 연결이 끊겼다. 이 문제를 막으려면 serial ID 기반 경로를 쓰는 게 낫다.
serial:
port: /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_...
페어링이 안 되는 기기: Zigbee2MQTT 지원 기기 목록에서 미리 확인하는 게 좋다. 목록에 있어도 간혹 안 되는 경우가 있는데, 이때는 공장 초기화 후 재시도하면 대부분 해결된다.
Mosquitto 연결 오류: Connection refused가 뜨면 Mosquitto가 실행 중인지 확인하고, 방화벽에서 1883포트가 열려 있는지 확인한다.
한 줄 정리
SONOFF 동글 + Zigbee2MQTT + Mosquitto 조합이면 Philips Hue, IKEA TRÅDFRI, Aqara 같은 Zigbee 기기를 허브 없이 Home Assistant에 직접 연결할 수 있다.
다음엔 Home Assistant 조명·전력 자동화 — 스마트 플러그와 모션 센서로 자동화 만들기를 다룬다.
참고 링크