Zigbee2MQTT(Z2M)로 Home Assistant Zigbee 기기 연동하기

안녕하세요. Home Assistant에서 Zigbee 기기를 연동하는 방법은 크게 두 가지입니다. HA 내장 솔루션인 ZHA(Zigbee Home Automation)와 Zigbee2MQTT(Z2M)입니다. 처음에는 설정이 간단한 ZHA를 사용했는데, 지원하지 않는 기기가 생기고 세밀한 설정이 필요해지면서 Z2M으로 전환하게 됐습니다. 오늘은 Z2M 설치부터 기기 페어링, HA 엔티티 생성까지 전 과정을 공유합니다.

 

□ Zigbee2MQTT란

Zigbee2MQTT는 Zigbee 기기와 MQTT 브로커 사이를 연결해 주는 오픈소스 소프트웨어입니다. 동작 방식은 다음과 같습니다.

- Zigbee USB 어댑터가 Zigbee 신호를 수신
- Z2M이 Zigbee 프로토콜을 해석해 MQTT 메시지로 변환
- MQTT 브로커(Mosquitto)를 통해 HA에 전달
- HA가 MQTT Discovery로 자동으로 엔티티 생성

ZHA와 비교한 Z2M의 장점은 다음과 같습니다.

- 지원 기기 수: Z2M은 3,500개 이상의 기기를 지원해 ZHA보다 훨씬 넓은 호환성을 제공
- 세밀한 설정: 기기별 클러스터 설정, 바인딩, OTA 업데이트 등 고급 기능 지원
- 독립성: HA와 독립적으로 동작해 HA 재시작 중에도 Zigbee 메시 네트워크 유지
- 활발한 커뮤니티: 새 기기 지원이 빠르게 추가됨

 

□ 필요한 준비물

Z2M 구성을 위해 필요한 것들입니다.

- Zigbee USB 어댑터: 저는 Sonoff Zigbee 3.0 USB Dongle Plus를 사용합니다. 가성비가 좋고 안정적인 제품입니다. Texas Instruments CC2652P 칩셋 기반으로 Z2M에서 공식 권장하는 어댑터 중 하나입니다.
- Home Assistant 서버: 이미 동작 중인 HA가 있어야 합니다.
- HA 애드온: Mosquitto MQTT 브로커, Zigbee2MQTT

USB 어댑터는 HA 서버의 USB 포트에 직접 연결합니다. USB 연장 케이블을 사용하면 간섭을 줄이고 수신 범위를 넓히는 데 도움이 됩니다.

 

□ Mosquitto MQTT 브로커 설치

Z2M은 MQTT 브로커를 통해 HA와 통신하므로, 먼저 MQTT 브로커를 설치해야 합니다.

- HA → 설정 → 애드온 → 애드온 스토어 → "Mosquitto broker" 검색
- 설치 후 "시작", "시작 시 실행" 옵션 활성화
- 설정 탭에서 logins 항목에 MQTT 접속 계정 추가 (username/password)
- HA의 MQTT 통합 자동으로 감지되면 "설정" 클릭해 통합 추가

Mosquitto가 설치되면 HA와 MQTT 통합이 자동으로 연결됩니다.

 

□ Zigbee2MQTT 애드온 설치 및 설정

Zigbee2MQTT는 공식 HA 애드온 스토어에는 없고, 별도 저장소를 추가해야 합니다.

- HA → 설정 → 애드온 → 애드온 스토어 → 우측 상단 "저장소 관리"
- https://github.com/zigbee2mqtt/hassio-zigbee2mqtt 주소 추가
- 새로 나타난 "Zigbee2MQTT" 애드온 설치

설치 후 설정 탭에서 기본 설정을 입력합니다.

mqtt:
  server: mqtt://core-mosquitto
  user: {MQTT 계정}
  password: {MQTT 비밀번호}
serial:
  port: /dev/ttyUSB0
homeassistant: true

serial.port는 USB 어댑터의 장치 경로입니다. /dev/ttyUSB0 또는 /dev/ttyACM0가 일반적이며, 정확한 경로는 HA의 "시스템 → 하드웨어" 메뉴에서 확인할 수 있습니다.

 

□ 기기 페어링

Z2M 애드온이 실행되면 Z2M 웹 UI에 접속할 수 있습니다 (HA 사이드바에 Z2M 아이콘 생성). 기기 페어링 방법입니다.

- Z2M 웹 UI 상단의 "Permit join" 버튼 클릭 (페어링 허용 상태로 전환)
- Zigbee 기기를 페어링 모드로 진입 (기기마다 방법이 다름. 보통 리셋 버튼 장누름)
- Z2M 웹 UI에 새 기기가 감지되면 자동으로 등록
- 기기 이름을 원하는 이름으로 변경 (예: "거실 모션 센서")
- HA에서 자동으로 새 엔티티가 생성됨

대부분의 기기는 페어링 시작 후 30초~2분 안에 인식됩니다. 인식이 안 되면 기기를 Z2M 코디네이터(USB 어댑터)에 가깝게 이동한 뒤 재시도합니다.

 

□ HA 엔티티 자동 생성 확인

Z2M과 HA MQTT Discovery가 연동되면, 기기 페어링 즉시 HA에 엔티티가 자동으로 생성됩니다. 확인 방법은 다음과 같습니다.

- HA → 설정 → 기기 및 서비스 → 통합 → MQTT
- MQTT 통합 아래에 Z2M을 통해 추가된 기기들이 나열됩니다.

각 기기의 엔티티는 센서 타입에 따라 자동으로 구분됩니다. 예를 들어 모션 센서는 binary_sensor.{이름}_occupancy, 온습도 센서는 sensor.{이름}_temperature 등으로 생성됩니다.

자동화에서 이 엔티티들을 바로 사용할 수 있어서 복잡한 추가 설정 없이 바로 자동화 구성이 가능합니다.

 

□ Z2M 사용 후기 및 팁

Z2M을 6개월 이상 사용하면서 느낀 점들입니다.

- ZHA 대비 지원 기기가 훨씬 넓습니다. 특히 중국산 Tuya 기기 같은 경우 ZHA에서 인식 못하는 걸 Z2M으로 잡아내는 경우가 많았습니다.
- Z2M 웹 UI가 편리합니다. 기기 상태, 네트워크 맵(메시 구성 시각화), OTA 업데이트를 웹 UI에서 바로 관리할 수 있습니다.
- 한 가지 팁: USB 어댑터를 USB 연장 케이블로 서버 본체와 분리해 두는 것을 추천합니다. USB 포트 근처에서 발생하는 2.4GHz 간섭을 줄여 수신 범위와 안정성이 개선됩니다.

 

□ 마무리

Zigbee2MQTT는 HA에서 Zigbee 기기를 연동하는 가장 유연하고 강력한 방법입니다. ZHA보다 설정이 조금 복잡하지만, 한 번 구성해 두면 훨씬 넓은 기기 호환성과 세밀한 제어 능력을 얻을 수 있습니다. Zigbee 기기를 많이 사용 중이거나, ZHA에서 지원 안 되는 기기를 연동하고 싶은 분들에게 Z2M으로의 전환을 강력히 추천드립니다.

감사합니다.