[Home Assistant] Zigbee2MQTT 2.0.0 업데이트 후 USB 어댑터 인식 오류 해결기

IOT/Home Assistant

[Home Assistant] Zigbee2MQTT 2.0.0 업데이트 후 USB 어댑터 인식 오류 해결기

wookingwoo 2025. 4. 27. 23:34

Home Assistant를 쓰면서 그동안 core 한 add-on들은 업데이트를 미루고 있었다.
사용하는 에드온이 많아지다 보니 하나하나 버전업하는 것도 귀찮았고, 무엇보다 '잘 돌아가는 건 건드리지 말자'는 마음이 컸다. 😅

그런데 오늘은 왠지 마음이 땡겨서, 오랜만에 모든 애드온을 한 번에 최신 버전으로 업그레이드했다.

그리고... 두둥. 마주하고 싶지 않던 문제가 터졌다.

이번에 문제가 생긴 주인공은 Zigbee2MQTT였다.

Zigbee2MQTT를 1.38.0-1 버전에서 2.2.1-1로 업데이트했더니, Zigbee USB 어댑터를 인식하지 못하는 이슈가 생긴 것이다.

Zigbee2MQTT는 Zigbee 장치들을 Home Assistant 같은 스마트홈 시스템에 연결할 수 있게 해주는 중간다리 역할을 하는 애드온이다. 쉽게 말하면, 각종 스마트 전구, 스위치, 센서 같은 Zigbee 기기들을 Home Assistant가 알아듣게 번역해 주는 통역사 같은 존재라고 보면 된다.

덕분에 집 안 Zigbee 장치들이 전부 먹통이 되고, 결국 불도 못 켜는 사태가 벌어졌다.

버그 터졌다고, 이젠 불도 못 켜는 집... 어두워 어두워... 😭
일단 문제부터 차근차근 고쳐보자.

문제 상황

애드온을 업데이트한 후, Zigbee2MQTT가 아래와 같은 에러를 뿜으며 실행되지 않았다.

Error: USB adapter discovery error (No valid USB adapter found). Specify valid 'adapter' and 'port' in your configuration.

주요 증상

Zigbee2MQTT가 실행되지 않고 바로 종료됨
로그에 "No valid USB adapter found" 메시지 출력
Home Assistant에서 Zigbee 기기 제어 불가

원인 분석

Zigbee2MQTT 2.0.0 이상 버전에서는 USB 어댑터 자동 인식 기능이 변경되어, 설정 파일에 어댑터 종류(adapter)와 포트(port)를 명확하게 지정해주어야 한다고 한다.

이전 버전에서는 알아서 잘 잡아줬던 포트와 어댑터 종류를,
이제는 configuration.yaml에 명확히 지정해 줘야 실행이 가능하다.

해결 방법

1. USB 어댑터 포트 확인

터미널에서 아래 명령어를 입력해 어댑터의 실제 포트를 확인한다.

ls -l /dev/serial/by-id

예시 결과:

/dev/serial/by-id/{your-id}

여기서 나온 경로(/dev/serial/by-id/{your-id})를 기억해 둔다.

2. configuration.yaml 파일 수정

zigbee2mqtt의 configuration.yaml 파일을 열고, 다음과 같이 설정을 추가/수정한다.

serial:
  port: /dev/serial/by-id/{your-id}
  adapter: zstack

port: 위에서 확인한 실제 어댑터 경로로 입력
adapter: 사용하는 어댑터 종류에 맞게 지정 (예: zstack, ezsp, deconz 등)

참고로, 대다수 CC2652 기반 동글은 zstack이다.

내가 구매한 동글도 CC2652 기반의 칩셋이라 adapter를 zstack로 명시했다.

[이전 포스팅] Zigbee Dongle 구매기 (ZBDongle-P vs ZBDongle-E): https://blog.wookingwoo.com/64

3. Home Assistant 재시작 또는 Zigbee2MQTT 재시작

설정 저장 후 Zigbee2MQTT 애드온을 재시작하니 정상적으로 동작했다.

마치며

Zigbee2MQTT를 2.0.0 이상으로 업데이트할 때는 configuration.yaml에 어댑터 종류와 포트를 명시해야 한다.

업데이트 전에는 꼭 설정 파일 백업을 해두고, 문제가 생기면 침착하게 로그부터 보는 습관을 들이자! ✍️

당황했지만 생각보다 어렵지 않게 해결할 수 있었다.

혹시 비슷한 문제를 겪고 있다면 이 글이 작은 도움이 되길 바랍니다.
궁금한 점이나 추가로 필요한 정보가 있으면 댓글로 편하게 남겨주세요!