Home Assistant (홈어시스턴트) Zigbee (지그비) 연동 - ② Z2M (Zigbee 2 MQTT)

이번 시간에는 Home Assistant(이하 HA)에 Zigbee(지그비, 이하 지그비) 연동하는 방식에 대해 알아보겠습니다.

이 글에서는 지그비 연동을 위해 알리익스프레스에서 저렴하게 구매가 가능한 [CC2531 동글]을 사용하겠습니다.

 

www.aliexpress.com/item/4000822997596.html?spm=a2g0s.9042311.0.0.27424c4dFcb3Fe

3.99US $ 30% OFF|Itead SONOFF Dongle Zigbee CC2531 USB Dongle Module Bare Board Packet Protocol Analyzer Interface Dongle Captur

 

 

HA를 설치하는 게시글은 다음 링크에 있습니다.

Home Assistant (홈어시스턴트) 설치 방법

Home Assistant (홈어시스턴트) 설치 방법

글에 앞서서, HA에서 지그비를 연동하는 방식은 일반적으로 많이 사용하는 2가지 방식이 있습니다.

 

① Z2M (Zigbee 2 MQTT, 이하 Z2M)을 사용하여 연동

② ZHA (Zigbee Home Automation, 이하 ZHA)를 사용하여 연동

 

두 가지 방식 모두 장단점이 있습니다.

 

ZHA 장점 : HA인터페이스와 통합되어 직관적으로 사용이 가능하며, Z2M에 비해 상대적으로 연동이 쉬움

ZHA 단점 : 일부 샤오미 센서 제품 및 Tuya센서들의 100% 페어링 상태를 담보하지 못하며, 경우에 따라 여러번 페어링을 시도해야 하는 문제가 발생. 일부 Tuya 노뉴트럴(중성선 없는 모델) 전등 스위치의 경우 2분마다 타이머 설정이 작동하여 전등이 자동으로 꺼지는 이슈가 있음. 지그비 라우터 장비에서 페어링을 진행하여도 모듈에 따라 페어링이 진행되지 않고 코디네이터에서만 진행되는 경우가 발생하기도 함.

 

Z2M 장점 : Z2M홈페이지에서 제공하는 다양한 지그비기기 연동정보를 참고할 수 있음. ZHA에서는 확인되지 않았던 각종 센싱 정보까지 HA로 추가로 넘겨주는것을 확인. 지그비 라우터 장비에서 페어링을 진행시에 잘 붙음. 샤오미/Tuya 지그비 장비가 한번에 페어링 됨. (장점이 더 많습니다.)

Z2M 단점 : HA에 통합된 ZHA보다 웹 GUI인터페이스가 구림(적응하면 볼만합니다.) 설치 방법이 ZHA에 비해 복잡함.

 

이 글에서는 먼저 Z2M으로 지그비를 연동하는 방법에 대해 설명하겠습니다.

 

1. 먼저 지그비 USB동글 CC2531을 라즈베리파이 USB포트에 삽입합니다. 

 

2. 인식이 제대로 되었는지 확인하기 위해서는 HA 로그인 후 좌측 메뉴에서 [Supervisor] 클릭 후 우측 상단 [System]을 클릭 후에 Host 탭에서 [...] 을 클릭 후에 [Hardware]를 클릭해줍니다.

 

<그림2. 지그비 동글 CC2531 인식 확인 화면>

3. 이후 팝업창에서 맨 위 serial: 로 되어있는 부분 중 CC2531모듈이 제대로 인식되었는지 확인합니다. USB타입 CC2531을 라즈베리파이에 연결시에, 대부분은 아래 그림과 같이 /dev/ttyAMA0  /dev/ttyACM0 (아래 그림상에 빨간네모가 위쪽과 묶여야 하는데 잘못표기되었습니다.)으로 연결이 됩니다.

<그림3. 지그비 동글 Hardware 정보 조회 화면>

4. 연결 된것을 확인하였으므로, 이후 단계 진행을 위해 HA의 고급모드를 활성화해보겠습니다. 좌측 하단의 사용자 이름(여기서는 admin)을 클릭하여 프로필 화면으로 가보면, 그림과 같이 고급모드를 설정하는 토글 버튼이 있습니다. 이것을 체크하여 활성화해줍니다.

<그림4. 고급모드 활성화 화면>

5. 이후, 좌측메뉴 [설정] 을 클릭하여 스크롤을 좀 내리면, [사용자] 메뉴가 활성화 된것을 확인할 수 있습니다. (위에서 고급모드를 활성화 하지 않으면 사용자가 보이지 않습니다.) 활성화된 [사용자] 메뉴를 클릭해줍니다.

<그림5. 고급모드를 통해 활성화된 사용자 화면>

6. MQTT 브로커용으로 사용할 사용자 계정을 만들어줍니다. 제 경우에는 표시이름/사용자이름을 mqtt로 지정하였습니다. 사용자이름(ID)와 비밀번호(PW)는 앞으로의 설정에 사용되니 기억해주시기 바랍니다. 이제 [만들기] 버튼을 클릭하여 MQTT용 사용자 계정을 생성해줍니다.

<그림6. MQTT용 사용자 계정 생성 화면>

7. 팝업창이 사라지며, MQTT사용자가 추가된 것을 확인할 수 있습니다.

<그림7. MQTT 사용자가 추가된 화면>

8. 이제 본격적으로 MQTT설정을 할 차례입니다. 먼저 MQTT 브로커를 설치합니다. MQTT 브로커는 간단하게 MQTT신호들을 총괄관리하는 서버개념으로 이해하시면 됩니다. HA 로그인 후 좌측 [Supervisor] 를 클릭 후, 상단 [Add-on Store]에서 [mqtt]를 검색합니다. Official add-ons에서 브로커인 [Moquitto broker] 를 클릭합니다.

<그림8. Supervisor에서 Moquitto broker 검색 화면>

9. 설치를 위해 중간에 [INSTALL] 버튼을 클릭합니다.

<그림9. MQTT 소개 및 설치 화면>

10. MQTT 브로커의 환경설정이 필요합니다. 설치완료 후 우측 상단의 [Configuration] 탭을 클릭하여, 다음 이미지를 참고하여 username과 password를 추가한 MQTT사용자 계정에 맞게 설정해준 후 [SAVE] 버튼을 클릭해줍니다.

 

수정 전 : logins값이 공란임

logins: []
anonymous: false
customize:
  active: false
  folder: mosquitto
certfile: fullchain.pem
keyfile: privkey.pem
require_certificate: false

수정 후 : logins값이 username과 password를 추가 (username과 password는 위에서 설정한 mqtt사용자 계정 정보로 입력하셔야 합니다.)

logins:
  - username: mqtt
    password: mqtt
anonymous: false
customize:
  active: false
  folder: mosquitto
certfile: fullchain.pem
keyfile: privkey.pem
require_certificate: false

티스토리 게시글 펌방지로 인해, 복사 붙여넣기가 안되시면 아래의 텍스트파일을 다운로드받아서 복사 붙여넣기 하시면 됩니다.

 

mqtt_idpw.txt

0.00MB

 

<그림10. MQTT 브로커에 로그인 계정 설정 화면>

 

11. 이제 다시 상단 Info 탭을 클릭하여, 다음 화면과 같이 Start on Boot, Watchdog 설정을 해줍니다. MQTT 브로커는 앞으로의 Z2M관리를 위한 필수서비스이므로 중단없이 실행하기 위해 Watchdog을 [활성화]해줍니다. 이후 [START] 버튼을 클릭합니다.

 

2021.03.17. 내용추가 : Home Assistant 한국어 번역이 업데이트 되면서, [Watchdog]은 [실행 감시]로 번역되었습니다. 참고하시기 바랍니다.

<그림11. MQTT 브로커 Watchdog 설정 및 서비스 시작 화면>

12. 서비스 START 버튼을 클릭 한 후에, 우측 상단 [Log] 탭을 클릭해줍니다. 정상적인 동작여부를 확인하기 위해 하단 [REFRESH] 버튼을 몇차례 눌러줍니다.

<그림12. MQTT 브로커 로그 화면>

13. MQTT브로커를 설정완료 하였다면, 이제 Z2M을 설치할 차례입니다. Z2M은 Zigbee2MQTT에서 관리되는 지그비 정보들을 MQTT로 보내주는 역할을 수행합니다. 또한, 앞으로의 Zigbee장비를 추가하는데에도 사용되는 애드온입니다. 좌측 메뉴의 [Supervisor] 클릭 후, 우측 [Add-on Store]를 클릭한 후에 우측 상단의 [...] 버튼을 클릭하여 [Repositories] 버튼을 클릭해줍니다. 이는 Zigbee2MQTT 애드온이 별도 github저장소에서 관리되기 때문입니다.

<그림13. Z2M 저장소 추가 화면>

14. Manage add-on repositories 창에서 다음의 주소를 복사&붙여넣기한 후 [ADD] 버튼을 눌러서 추가해줍니다.

https://github.com/danielwelch/hassio-zigbee2mqtt

티스토리 게시글 펌방지로 인해, 복사 붙여넣기가 안되시면 아래의 텍스트파일을 다운로드받아서 복사 붙여넣기 하시면 됩니다.

z2m_repository_url.txt

0.00MB

 

 

<그림14. Z2M 애드온 저장소 추가 화면>

15. Zigbee2MQTT 저장소가 추가된 것을 아래 그림과 같이 확인 후 [CLOSE] 버튼을 클릭합니다.

<그림15. Z2M 애드온 저장소 추가 완료 화면>

16. 이제 Home Assistant Add-on: Zigbee2mqtt 저장소 목록이 추가된것을 확인할 수 있습니다. 여기서 아래 그림과 같이 설치를 위해 [Zigbee2mqtt] 버튼을 클릭합니다. (참고: Zigbee2mqtt Edge는 해당 저장소에서 개발중인 버전으로 여기서는 사용하지 않습니다.)

<그림16. Z2M 애드온 저장소에서 Zigbee2mqtt 목록 조회 화면>

17. Zigbee2mqtt 애드온 정보 조회 화면에서 [INSTALL] 버튼을 클릭하여 Z2M을 설치해줍니다. MQTT 브로커보다는 설치시간이 조금 소요됩니다.

<그림17. Z2M 애드온 정보 조회 및 설치 화면>

18. 설치가 완료되면 [Configuration] 탭을 클릭하여, 아래 이미지를 참고하여 user, password 정보를 위의 단계에서 설정한 MQTT 사용자 계정 정보(user, password)로 입력하여 줍니다. 추가로 advanced에서 지그비 채널값을 변경해줄 수 있는데 기본값11채널은 와이파이 2.4기가 영역에서 중복되어 통신지연/누락 현상이 있을 수 있으므로, 원활한 통신을 위해 25채널로 변경하여 줍니다.

 

<그림18. Z2M 사용자 계정정보 입력 및 지그비 채널 변경 화면>

2021.03.17. 내용추가 : Z2M 버전이 업데이트 되면서, ID/PW 입력 기본값이 내부 애드온 페이지의 setting 탭으로 이동하였습니다. (아래 이미지 서술) 위 화면에서는 채널변경만 진행하시면 됩니다.

 

<그림18-1. Z2M MQTT 사용자 계정정보 설정화면>

<그림18-2. Z2M MQTT 사용자 계정정보 설정화면 / 하단 SUBMIT버튼 클릭 후 우측 상단에 Restart>

 

19. 스크롤을 내려서 [SAVE] 버튼을 클릭하여 저장해줍니다.

<그림19. Z2M 환경설정 저장 화면>

20. 다시 [Info] 탭을 클릭하여, Watchdog과 Show in sidebar 옵션을 선택해줍니다. Show in sidebar 옵션을 선택하게 되면, 앞으로 자주 사용하게되는 메뉴인 Zigbee2mqtt 메뉴를 좌측 메뉴에서 빠르게 접근할 수 있습니다. 이후 [START] 버튼을 클릭하여 Z2M 애드온을 실행하여 줍니다.

<그림20. Z2M 애드온 정보 화면>

21. 이제 마지막으로 HA에서 Z2M에 연동된 지그비 디바이스를 자동으로 가져오기 위한 절차만 남았습니다. 좌측 메뉴 하단 [설정] 버튼을 클릭하여 [통합 구성요소]를 클릭합니다.

<그림21. HA설정페이지 화면>

22. 발견된 구성요소에 MQTT가 보이는것을 확인할 수 있습니다. [설정하기] 버튼을 클릭한 후 팝업창에서 [확인] 버튼을 클릭합니다.

<그림22. 통합 구성요소 MQTT 추가 화면>

23. MQTT 통합구성요소 화면 카드에서, [설정] 버튼을 클릭합니다.

<그림23. 통합구성요소에서 MQTT가 추가된 화면>

24. MQTT설정화면에서 [RE-CONFIGURE MQTT] 버튼을 클릭해줍니다.

<그림24. 통합구성요소 MQTT 설정 화면>

25. 팝업창에서 위 단계에서 추가한 MQTT 사용자 계정 정보를 입력해준 후 [확인] 버튼을 클릭합니다.

<그림25. MQTT 브로커 연결 정보 설정 화면>

 

26. MQTT 옵션 중 상단에 장치 검색 활성화가 체크되어있는지 반드시 확인하신 후, 하단 [확인] 버튼을 클릭합니다.

<그림26. MQTT 옵션 화면>

 

27. 옵션이 성공적으로 저장되었다는 메시지를 확인한 후 [완료] 버튼을 클릭합니다.

<그림27. MQTT 옵션 저장 완료 화면>

28. 정상적으로 MQTT 통신이 되는지 확인하기 위해, 하단 토픽 내용 들어보기에서 [청취할 토픽] 란에 [test]를 입력 후 [청취 시작] 버튼을 클릭합니다. 상단의 패킷 발행 부분에서 토픽란에 [test]를 입력 후 페이로드 칸 숫자 1 옆에 아무글자나 입력하여 [발행] 버튼을 클릭해봅니다. 아무글자나 입력한 내용이 토픽내용 들어보기에 나타나야 정상적으로 MQTT 설정이 완료된 것입니다.

<그림28. MQTT테스트를 위한 토픽채널에서의 패킷 발행 화면>

29. 이제 Z2M의 모든 설정이 끝났습니다. 앞으로 지그비 디바이스의 페어링(연동/연결)이 필요하다면, 좌측 메뉴에서 [Zigbee2mqtt] 메뉴를 클릭한 후, 우측 화면에서 [Permit join (All)] 버튼을 클릭하여 페어링을 할 수 있습니다. 여러대의 지그비 게이트웨이(허브)를 사용하는 경우, 혼선 방지를 위해, 원하는 지그비 디바이스가 페어링이 되었다면 반드시 동일 위치의 [Disable join (All)] 버튼을 눌러서 상시페이링 모드를 해제해주시기 바랍니다.

<그림29. Z2M 정보조회 및 페어링 방식 화면>

다음시간에는 ZHA(Zigbee Home Assistant)로 설정하는 방법에 대해 알아보겠습니다.

 

ZHA로 지그비를 HA에 통합하는 절차는 다음 링크에 있습니다.

Home Assistant (홈어시스턴트) Zigbee (지그비) 연동 - ① ZHA (Zigbee Home Assistant)

Home Assistant (홈어시스턴트) Zigbee (지그비) 연동 - ① ZHA (Zigbee Home Assistant)

 

감사합니다.