Zigbee2MQTT 구조를 이해하고 사용을 위한 설치 및 설정 방법

Zigbee2MQTT를 사용하기 위한 설치 및 사용 방법을 쉽게 이해할 수 있도록 단계별로 정리해봤습니다.

필요한 장비

1. ZZHA Zigbee 어댑터: 이것은 컴퓨터와 Zigbee 무선통신을 연결하는 장치입니다. USB, GPIO, WIFI 또는 이더넷을 통해 연결할 수 있습니다. CC2652 또는 CC1352로 시작하는 칩이 포함된 어댑터를 사용하는 것이 좋습니다.
2. Raspberry Pi 또는 다른 서버: Zigbee2MQTT를 실행할 컴퓨터나 라즈베리 파이입니다. MQTT 브로커(통신을 중계해주는 프로그램)가 필요하며, 대표적으로 Mosquitto를 사용합니다.
3. Zigbee 장치: Zigbee2MQTT와 연결할 Zigbee 장치입니다.
4. USB 케이블 (선택 사항): 네트워크 범위와 안정성을 높이기 위해 USB 연장 케이블을 사용할 수 있습니다.

설치 과정

1. Zigbee 어댑터 찾기

• USB Zigbee 어댑터: 어댑터를 컴퓨터에 연결한 후, dmesg 명령어로 컴퓨터가 어댑터를 인식했는지 확인합니다.
• 네트워크 Zigbee 어댑터: 네트워크 어댑터를 사용하는 경우, 어댑터의 IP 주소를 알아내야 합니다. 대부분의 어댑터는 mDNS를 통해 자동으로 감지됩니다.

2. Zigbee2MQTT 설정 및 시작

• 폴더 생성: Zigbee2MQTT를 위한 폴더를 만듭니다.
• 설정 파일 준비: docker-compose.yml 파일을 생성하고 Zigbee2MQTT와 MQTT 서버에 대한 설정을 정의합니다.
• Zigbee2MQTT 설정 파일 생성: zigbee2mqtt-data/configuration.yaml에 Zigbee2MQTT의 구체적인 설정을 작성합니다.
• 서비스 시작: docker compose up -d 명령어로 Zigbee2MQTT를 시작합니다.
• 로그 확인: docker compose logs -f 명령어로 서비스가 정상적으로 작동하는지 확인합니다.

3. 장치 연결

• 장치 페어링: 지원되는 장치 목록을 참조하여 장치를 Zigbee2MQTT와 페어링합니다.
• 설정 변경: 모든 장치를 연결한 후, configuration.yaml 파일에서 permit_join을 false로 설정하여 네트워크를 안전하게 유지합니다.

주의사항

• 어댑터를 구매하기 전에 권장 사항을 확인하여 필요한 추가 구성이 있는지 확인하십시오.
• 네트워크 어댑터를 사용하는 경우, IP 주소 및 통신 포트를 확인해야 합니다.
• 모든 설정이 완료된 후에는 permit_join을 false로 설정하여 Zigbee 네트워크를 보호합니다.

 

설치하는 과정을 단계별로 정리하면 아래와 같습니다.

1. 도커 설치
   • 우선 도커를 설치합니다. 이는 공식 도커 웹사이트에서 제공하는 설치 가이드를 따르면 됩니다.
2. Zigbee2MQTT 도커 이미지 다운로드
   • 터미널 또는 커맨드 프롬프트를 열고, Zigbee2MQTT의 공식 도커 이미지를 다운로드합니다. 
   • docker pull koenkk/zigbee2mqtt
3. 컨테이너 생성
   • Zigbee2MQTT를 실행할 도커 컨테이너를 생성합니다. 아래 명령어를 사용하면 됩니다.

     docker run -it -v /path/to/data:/app/data -v /path/to/configuration.yaml:/app/configuration.yaml --device=/dev/ttyUSB0 --network=host --name=zigbee2mqtt koenkk/zigbee2mqtt

     여기서 /path/to/data와 /path/to/configuration.yaml를 호스트 시스템의 실제 경로로 대체해야 합니다. /dev/ttyUSB0는 Zigbee 장치에 대한 포트로, 필요에 따라 조정할 수 있습니다.
4. 설정 파일 편집
   • 호스트 시스템에서 /path/to/configuration.yaml 파일을 열어 Zigbee2MQTT 설정을 수정합니다. 필요한 경우 Zigbee 장치의 시리얼 포트 등을 설정합니다.
5. 컨테이너 재시작
   • 설정을 저장한 후에는 도커 컨테이너를 재시작하여 변경 사항을 적용합니다.

     docker restart zigbee2mqtt

6. 로그 확인
   • 필요에 따라 Zigbee2MQTT 컨테이너의 로그를 확인하여 문제를 해결합니다.

     docker logs zigbee2mqtt

이러한 단계를 따르면 Zigbee2MQTT를 도커 환경에서 성공적으로 구성할 수 있습니다.

1. MQTT 브로커 설치
   • 도커를 사용하여 MQTT 브로커를 설치합니다. Eclipse Mosquitto를 사용하는 경우 다음 명령어를 실행합니다.

     docker run -d -p 1883:1883 --name=mosquitto eclipse-mosquitto

2. Zigbee2MQTT 설정 수정
   • Zigbee2MQTT 설정 파일 (/path/to/configuration.yaml)을 열어 MQTT 브로커의 정보를 추가합니다. 다음과 같이 mqtt 섹션을 찾고 브로커의 호스트 및 포트를 설정합니다.

     mqtt:
       base_topic: zigbee2mqtt
       server: 'mqtt://mqtt_host:1883'

3. Zigbee2MQTT 컨테이너 재시작
   • Zigbee2MQTT 컨테이너를 재시작하여 새로운 MQTT 브로커 설정을 적용합니다.

     docker restart zigbee2mqtt

4. 확인 및 테스트
   • Zigbee2MQTT와 MQTT 브로커가 정상적으로 동작하는지 확인하기 위해 MQTT 클라이언트를 사용하거나 MQTT Explorer와 같은 도구를 이용합니다.
   • Zigbee2MQTT에서 발생하는 이벤트 및 상태를 MQTT 브로커를 통해 확인할 수 있어야 합니다.

이렇게하면 Zigbee2MQTT와 MQTT 브로커가 함께 동작하는 환경을 구성할 수 있습니다. 필요에 따라 Mosquitto의 더 많은 설정을 변경하려면 Mosquitto 설정 파일에 대해 공식 문서를 참조하세요.

1. Zigbee2MQTT WebUI 컨테이너 추가
   • Zigbee2MQTT WebUI를 사용하기 위해 WebUI 컨테이너를 추가합니다. 다음 명령어를 사용합니다.

     docker run -it -v /path/to/zigbee2mqtt/data:/app/data -v /path/to/zigbee2mqtt/configuration.yaml:/app/configuration.yaml -p 8880:8880 --network=host --name=zigbee2mqtt-ui nlecoy/zigbee2mqttassistant

     주의: /path/to/zigbee2mqtt/data와 /path/to/zigbee2mqtt/configuration.yaml는 Zigbee2MQTT의 데이터 및 설정 파일이 있는 실제 경로로 대체되어야 합니다.
2. WebUI 접속
   • 웹 브라우저에서 http://localhost:8880 또는 호스트의 IP 주소와 포트를 사용하여 Zigbee2MQTT WebUI에 접속합니다.
3. 장치 등록
   • WebUI에 접속한 후, 좌측 메뉴에서 "Coordinator"를 선택합니다.
   • "Add Device" 버튼을 클릭하여 새로운 Zigbee 장치를 등록합니다.
   • 등록하려는 Zigbee 장치를 페어링 모드로 설정하고 "Start Pairing" 버튼을 클릭합니다.
   • Zigbee 장치가 성공적으로 페어링되면 WebUI에서 해당 장치의 정보가 나타납니다.
4. 설정 저장
   • Zigbee2MQTT WebUI에서 장치를 등록한 후에는 변경 사항을 저장합니다.
5. Zigbee2MQTT 재시작
   • 변경 사항을 적용하기 위해 Zigbee2MQTT 컨테이너를 재시작합니다.

     docker restart zigbee2mqtt

이제 Zigbee2MQTT WebUI를 통해 Zigbee 장치를 쉽게 등록하고 관리할 수 있습니다. 호스트 및 포트는 필요에 따라 설정 파일에서 조정할 수 있습니다.

1. MQTT 클라이언트 설치
   • MQTT 브로커에서 발행되는 메시지를 확인하기 위해 MQTT 클라이언트를 설치합니다. 여러 옵션 중 하나를 선택하여 설치할 수 있습니다. 예를 들어, mosquitto_sub을 사용하는 방법은 다음과 같습니다.

     sudo apt-get install mosquitto-clients

2. MQTT 브로커 모니터링
   • Zigbee2MQTT에서 발행하는 정보를 MQTT 브로커에서 모니터링하려면 다음 명령어를 사용합니다.

     mosquitto_sub -h localhost -t 'zigbee2mqtt/#' -v

     위 명령어는 로컬에서 실행 중인 MQTT 브로커에 연결하고, zigbee2mqtt/# 토픽에 대한 모든 메시지를 출력합니다.
3. 장치 정보 확인
   • Zigbee2MQTT는 zigbee2mqtt/ 토픽을 통해 정보를 발행합니다. 예를 들어, 새로 추가한 Zigbee 장치의 정보는 zigbee2mqtt/your_device_name 토픽에서 확인할 수 있습니다.
4. 디버그 모드 활성화 (선택 사항)
   • Zigbee2MQTT에서 디버그 정보를 확인하려면 설정 파일 (configuration.yaml)에서 디버그 모드를 활성화합니다.

     advanced:
       log_level: debug

     변경 사항을 저장한 후에는 Zigbee2MQTT 컨테이너를 재시작하여 적용합니다.
5. 디버그 정보 모니터링 (선택 사항)
   • 디버그 모드를 활성화한 경우, MQTT 브로커 모니터링 명령을 실행하여 디버그 정보를 확인합니다.

이제 MQTT 브로커를 통해 Zigbee2MQTT에서 수집된 정보를 모니터링할 수 있습니다. 필요에 따라 추가로 MQTT 클라이언트 도구를 사용하거나 웹 기반의 MQTT Explorer와 같은 도구를 활용할 수 있습니다.

 

잘 알려진 Home Assistant와 Zigbee2MQTT를 연동하여 자동화를 구성하는 방법을 단계별로 설명합니다.

1. Home Assistant 설치 및 설정
   • Home Assistant를 설치하고 기본 설정을 마칩니다. 필요에 따라 Home Assistant OS, Home Assistant Supervised, 또는 Home Assistant Container를 선택할 수 있습니다.
2. Zigbee2MQTT 통합 추가
   • Home Assistant의 홈페이지로 이동하고, "Configuration" 메뉴에서 "Integrations"을 선택합니다.
   • "Zigbee2MQTT"를 검색하여 Zigbee2MQTT 통합을 추가합니다. 필요한 정보를 입력하고 연동을 완료합니다.
3. 연동된 장치 확인
   • Home Assistant의 홈페이지에서 "Configuration" 메뉴에서 "Devices"를 선택하여 Zigbee2MQTT를 통해 연동된 Zigbee 장치를 확인합니다.
4. 자동화 스크립트 작성
   • "Configuration" 메뉴에서 "Automations"을 선택하여 자동화 스크립트를 작성합니다.
     예를 들어, Zigbee 장치의 상태 변화에 대한 자동화를 구성하려면 다음과 같은 스크립트를 작성할 수 있습니다.

     alias: Zigbee Device State Change
     trigger:
       platform: state
       entity_id: binary_sensor.your_zigbee_device
     action:
       service: notify.notify
       data_template:
         message: "Zigbee device state changed to {{ states('binary_sensor.your_zigbee_device') }}"

5. 자동화 스크립트 저장
   • 작성한 자동화 스크립트를 저장하고, 변경 사항을 Home Assistant에 적용합니다.
6. 자동화 테스트
   • Zigbee 장치의 상태를 변경하여 자동화가 제대로 작동하는지 확인합니다.
7. 설정 저장 및 재시작
   • 변경 사항을 모두 저장하고 Home Assistant를 재시작하여 적용합니다.

이제 Zigbee2MQTT와 Home Assistant가 연동되어 Zigbee 장치의 상태에 따라 자동화가 동작합니다. 필요에 따라 자동화 스크립트를 수정하거나 추가적인 세부 설정을 적용할 수 있습니다.