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

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에 어댑터 종류와 포트를 명시해야 한다.

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

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

 

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