Zigbee2MQTT를 사용하기 위한 설치 및 사용 방법을 쉽게 이해할 수 있도록 단계별로 정리해봤습니다.
필요한 장비
- ZZHA Zigbee 어댑터: 이것은 컴퓨터와 Zigbee 무선통신을 연결하는 장치입니다. USB, GPIO, WIFI 또는 이더넷을 통해 연결할 수 있습니다. CC2652 또는 CC1352로 시작하는 칩이 포함된 어댑터를 사용하는 것이 좋습니다.
- Raspberry Pi 또는 다른 서버: Zigbee2MQTT를 실행할 컴퓨터나 라즈베리 파이입니다. MQTT 브로커(통신을 중계해주는 프로그램)가 필요하며, 대표적으로 Mosquitto를 사용합니다.
- Zigbee 장치: Zigbee2MQTT와 연결할 Zigbee 장치입니다.
- 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 네트워크를 보호합니다.
설치하는 과정을 단계별로 정리하면 아래와 같습니다.
- 도커 설치
- 우선 도커를 설치합니다. 이는 공식 도커 웹사이트에서 제공하는 설치 가이드를 따르면 됩니다.
- Zigbee2MQTT 도커 이미지 다운로드
- 터미널 또는 커맨드 프롬프트를 열고, Zigbee2MQTT의 공식 도커 이미지를 다운로드합니다.
docker pull koenkk/zigbee2mqtt
- 컨테이너 생성
- 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 장치에 대한 포트로, 필요에 따라 조정할 수 있습니다.
- Zigbee2MQTT를 실행할 도커 컨테이너를 생성합니다. 아래 명령어를 사용하면 됩니다.
- 설정 파일 편집
- 호스트 시스템에서
/path/to/configuration.yaml
파일을 열어 Zigbee2MQTT 설정을 수정합니다. 필요한 경우 Zigbee 장치의 시리얼 포트 등을 설정합니다.
- 호스트 시스템에서
- 컨테이너 재시작
- 설정을 저장한 후에는 도커 컨테이너를 재시작하여 변경 사항을 적용합니다.
docker restart zigbee2mqtt
- 설정을 저장한 후에는 도커 컨테이너를 재시작하여 변경 사항을 적용합니다.
- 로그 확인
- 필요에 따라 Zigbee2MQTT 컨테이너의 로그를 확인하여 문제를 해결합니다.
docker logs zigbee2mqtt
- 필요에 따라 Zigbee2MQTT 컨테이너의 로그를 확인하여 문제를 해결합니다.
이러한 단계를 따르면 Zigbee2MQTT를 도커 환경에서 성공적으로 구성할 수 있습니다.
- MQTT 브로커 설치
- 도커를 사용하여 MQTT 브로커를 설치합니다. Eclipse Mosquitto를 사용하는 경우 다음 명령어를 실행합니다.
docker run -d -p 1883:1883 --name=mosquitto eclipse-mosquitto
- 도커를 사용하여 MQTT 브로커를 설치합니다. Eclipse Mosquitto를 사용하는 경우 다음 명령어를 실행합니다.
- Zigbee2MQTT 설정 수정
- Zigbee2MQTT 설정 파일 (
/path/to/configuration.yaml
)을 열어 MQTT 브로커의 정보를 추가합니다. 다음과 같이mqtt
섹션을 찾고 브로커의 호스트 및 포트를 설정합니다.mqtt: base_topic: zigbee2mqtt server: 'mqtt://mqtt_host:1883'
- Zigbee2MQTT 설정 파일 (
- Zigbee2MQTT 컨테이너 재시작
- Zigbee2MQTT 컨테이너를 재시작하여 새로운 MQTT 브로커 설정을 적용합니다.
docker restart zigbee2mqtt
- Zigbee2MQTT 컨테이너를 재시작하여 새로운 MQTT 브로커 설정을 적용합니다.
- 확인 및 테스트
- Zigbee2MQTT와 MQTT 브로커가 정상적으로 동작하는지 확인하기 위해 MQTT 클라이언트를 사용하거나 MQTT Explorer와 같은 도구를 이용합니다.
- Zigbee2MQTT에서 발생하는 이벤트 및 상태를 MQTT 브로커를 통해 확인할 수 있어야 합니다.
이렇게하면 Zigbee2MQTT와 MQTT 브로커가 함께 동작하는 환경을 구성할 수 있습니다. 필요에 따라 Mosquitto의 더 많은 설정을 변경하려면 Mosquitto 설정 파일에 대해 공식 문서를 참조하세요.
- 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의 데이터 및 설정 파일이 있는 실제 경로로 대체되어야 합니다.
- Zigbee2MQTT WebUI를 사용하기 위해 WebUI 컨테이너를 추가합니다. 다음 명령어를 사용합니다.
- WebUI 접속
- 웹 브라우저에서
http://localhost:8880
또는 호스트의 IP 주소와 포트를 사용하여 Zigbee2MQTT WebUI에 접속합니다.
- 웹 브라우저에서
- 장치 등록
- WebUI에 접속한 후, 좌측 메뉴에서 "Coordinator"를 선택합니다.
- "Add Device" 버튼을 클릭하여 새로운 Zigbee 장치를 등록합니다.
- 등록하려는 Zigbee 장치를 페어링 모드로 설정하고 "Start Pairing" 버튼을 클릭합니다.
- Zigbee 장치가 성공적으로 페어링되면 WebUI에서 해당 장치의 정보가 나타납니다.
- 설정 저장
- Zigbee2MQTT WebUI에서 장치를 등록한 후에는 변경 사항을 저장합니다.
- Zigbee2MQTT 재시작
- 변경 사항을 적용하기 위해 Zigbee2MQTT 컨테이너를 재시작합니다.
docker restart zigbee2mqtt
- 변경 사항을 적용하기 위해 Zigbee2MQTT 컨테이너를 재시작합니다.
이제 Zigbee2MQTT WebUI를 통해 Zigbee 장치를 쉽게 등록하고 관리할 수 있습니다. 호스트 및 포트는 필요에 따라 설정 파일에서 조정할 수 있습니다.
- MQTT 클라이언트 설치
- MQTT 브로커에서 발행되는 메시지를 확인하기 위해 MQTT 클라이언트를 설치합니다. 여러 옵션 중 하나를 선택하여 설치할 수 있습니다. 예를 들어,
mosquitto_sub
을 사용하는 방법은 다음과 같습니다.sudo apt-get install mosquitto-clients
- MQTT 브로커에서 발행되는 메시지를 확인하기 위해 MQTT 클라이언트를 설치합니다. 여러 옵션 중 하나를 선택하여 설치할 수 있습니다. 예를 들어,
- MQTT 브로커 모니터링
- Zigbee2MQTT에서 발행하는 정보를 MQTT 브로커에서 모니터링하려면 다음 명령어를 사용합니다.
위 명령어는 로컬에서 실행 중인 MQTT 브로커에 연결하고,mosquitto_sub -h localhost -t 'zigbee2mqtt/#' -v
zigbee2mqtt/#
토픽에 대한 모든 메시지를 출력합니다.
- Zigbee2MQTT에서 발행하는 정보를 MQTT 브로커에서 모니터링하려면 다음 명령어를 사용합니다.
- 장치 정보 확인
- Zigbee2MQTT는
zigbee2mqtt/
토픽을 통해 정보를 발행합니다. 예를 들어, 새로 추가한 Zigbee 장치의 정보는zigbee2mqtt/your_device_name
토픽에서 확인할 수 있습니다.
- Zigbee2MQTT는
- 디버그 모드 활성화 (선택 사항)
- Zigbee2MQTT에서 디버그 정보를 확인하려면 설정 파일 (
configuration.yaml
)에서 디버그 모드를 활성화합니다.
변경 사항을 저장한 후에는 Zigbee2MQTT 컨테이너를 재시작하여 적용합니다.advanced: log_level: debug
- Zigbee2MQTT에서 디버그 정보를 확인하려면 설정 파일 (
- 디버그 정보 모니터링 (선택 사항)
- 디버그 모드를 활성화한 경우, MQTT 브로커 모니터링 명령을 실행하여 디버그 정보를 확인합니다.
이제 MQTT 브로커를 통해 Zigbee2MQTT에서 수집된 정보를 모니터링할 수 있습니다. 필요에 따라 추가로 MQTT 클라이언트 도구를 사용하거나 웹 기반의 MQTT Explorer와 같은 도구를 활용할 수 있습니다.
잘 알려진 Home Assistant와 Zigbee2MQTT를 연동하여 자동화를 구성하는 방법을 단계별로 설명합니다.
- Home Assistant 설치 및 설정
- Home Assistant를 설치하고 기본 설정을 마칩니다. 필요에 따라 Home Assistant OS, Home Assistant Supervised, 또는 Home Assistant Container를 선택할 수 있습니다.
- Zigbee2MQTT 통합 추가
- Home Assistant의 홈페이지로 이동하고, "Configuration" 메뉴에서 "Integrations"을 선택합니다.
- "Zigbee2MQTT"를 검색하여 Zigbee2MQTT 통합을 추가합니다. 필요한 정보를 입력하고 연동을 완료합니다.
- 연동된 장치 확인
- Home Assistant의 홈페이지에서 "Configuration" 메뉴에서 "Devices"를 선택하여 Zigbee2MQTT를 통해 연동된 Zigbee 장치를 확인합니다.
- 자동화 스크립트 작성
- "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') }}"
- "Configuration" 메뉴에서 "Automations"을 선택하여 자동화 스크립트를 작성합니다.
- 자동화 스크립트 저장
- 작성한 자동화 스크립트를 저장하고, 변경 사항을 Home Assistant에 적용합니다.
- 자동화 테스트
- Zigbee 장치의 상태를 변경하여 자동화가 제대로 작동하는지 확인합니다.
- 설정 저장 및 재시작
- 변경 사항을 모두 저장하고 Home Assistant를 재시작하여 적용합니다.
이제 Zigbee2MQTT와 Home Assistant가 연동되어 Zigbee 장치의 상태에 따라 자동화가 동작합니다. 필요에 따라 자동화 스크립트를 수정하거나 추가적인 세부 설정을 적용할 수 있습니다.
728x90
댓글