HomeAssistant에 Tuya(투야) 장치를 추가하는 방법은 크게 두 가지입니다: 공식 Tuya 통합(클라우드, 가장 간단)과 Tuya Local(로컬 제어, 응답은 빠르지만 설정이 다소 번거로움)입니다.
초보 사용자에게는 공식 Tuya 통합을 강력히 추천합니다. 현재 버전(2025.12.x)은 단계가 크게 간소화되어, 예전처럼 개발자 계정을 등록하거나 Access ID를 신청하고 개발자 체험 기간 만료를 걱정할 필요가 없습니다. 이제는 “사용자 코드”와 휴대폰 앱 QR 스캔만 있으면 됩니다.
아래는 HomeAssistant 2025.12.2 버전을 기반으로 한 자세한 초보자 튜토리얼입니다.
🟢 방법 1: 공식 Tuya 통합 (초보자 추천)
이 방법이 가장 간단합니다. 설정을 마치면 휴대폰의 Tuya Smart 또는 Smart Life 앱에서 볼 수 있는 장치가 HomeAssistant에 자동으로 동기화됩니다.
1. 준비 작업
- 휴대폰 앱: 휴대폰에 Tuya Smart 또는 Smart Life 앱이 설치되어 있는지 확인합니다.
- 계정: 이미 가입 및 로그인되어 있고, 앱에 스마트 장치(콘센트, 전구 등)가 추가되어 있어야 합니다.
- 네트워크: 휴대폰과 HomeAssistant가 같은 로컬 네트워크에 있는 것이 좋지만, 클라우드 통합에서는 필수는 아닙니다.
2. “사용자 코드” (User Code) 가져오기
이것이 새 버전 통합에서 가장 중요한 단계이며, 예전의 복잡한 개발자 계정을 대체합니다.
- 휴대폰에서 Tuya Smart 또는 Smart Life 앱을 엽니다.
- 오른쪽 아래의 “나” (Me)를 탭합니다.
- 오른쪽 위의 육각형 설정 아이콘 (⚙️)을 탭합니다.
- 첫 번째 항목인 “계정과 보안” (Account and Security)을 탭합니다.
- 페이지 중앙에서 “사용자 코드” (User Code)를 볼 수 있습니다.
- 코드 옆의 “복사” 버튼을 탭합니다(또는 직접 메모합니다).
주의
: “사용자 코드”를 찾을 수 없다면, 앱이 최신 버전으로 업데이트되었는지 확인하세요.
3. HomeAssistant에 통합 추가하기
- 컴퓨터 브라우저에서 HomeAssistant 백엔드를 엽니다(보통 http://homeassistant.local:8123).
- 왼쪽 사이드바에서 “설정” (Settings)을 클릭합니다.
- “장치 및 서비스” (Devices & Services)를 선택합니다.
- 오른쪽 아래의 파란색 버튼 “+ 통합 추가” (+ ADD INTEGRATION)를 클릭합니다.
- 검색창에 Tuya를 입력하고 나타나는 Tuya 아이콘을 클릭합니다.
4. 페어링 진행
- HomeAssistant가 띄우는 창에서 사용자 코드를 입력하라는 요청이 나옵니다.
- 방금 휴대폰 앱에서 가져온 사용자 코드를 붙여넣고 “제출”을 클릭합니다.
- 화면에 QR 코드가 표시됩니다.
- 즉시 휴대폰을 들고 Tuya/Smart Life 앱을 엽니다:
- 앱 홈 화면(“가정” 페이지)으로 돌아갑니다.
- 오른쪽 위의 “+”를 탭하고 “스캔”을 선택합니다.
- 컴퓨터 화면의 QR 코드를 스캔합니다.
휴대폰에 로그인 확인 안내가 뜨면 “로그인 확인”을 탭합니다.
5. 완료
- HomeAssistant 페이지가 자동으로 새로고침되며 “성공!”이 표시됩니다.
- 장치를 특정 방에 할당할 수 있습니다(관리를 위해 영역을 지정하는 것을 권장합니다). 그런 다음 “완료”를 클릭합니다.
- 이제 “개요” (Overview) 패널로 가면 Tuya 장치가 나타나 있고 전원을 켜고 끌 수 있습니다!
🔵 방법 2: Tuya Local (고급, 로컬 제어)
공식 통합의 응답이 느리거나 인터넷이 끊기면 사용할 수 없다면 이 방법을 시도해 보세요. HACS를 통해 설치하며, 다음을 구현할 수 있습니다
간단한 흐름 (참고용):
- 먼저 HACS(Home Assistant Community Store)를 설치해야 합니다.
- HACS에서 Tuya Local을 검색해 다운로드합니다(LocalTuya가 아님에 주의하세요. Tuya Local의 설정이 더 친화적입니다).
- HomeAssistant를 재시작합니다.
- “장치 및 서비스”에서 통합을 추가하고 Tuya Local을 검색합니다.
- 새 버전의 장점: 현재 Tuya Local도 위의 “QR 스캔” 모드로 Key를 자동으로 가져올 수 있어, 개발자 플랫폼에서 패킷을 캡처할 필요가 없습니다. 매우 편리합니다.
자주 묻는 질문 (Q&A)
Q: 예전 튜토리얼에서는 iot.tuya.com 개발자 계정을 등록하고 Access ID와 Secret이 필요하며 6개월마다 갱신해야 한다고 했는데, 이제 필요 없나요? A: 필요 없습니다! 그것은 구버전(2024년 초 이전)의 절차입니다. 현재 공식 통합은 “스마트 홈 PaaS” 모델을 사용하므로, 일반 사용자는 앱에서 QR 코드만 스캔하면 되어 번거로운 개발자 체험 기간 문제를 완전히 피할 수 있습니다.
Q: HomeAssistant에서 장치가 “사용 불가”로 표시되면 어떻게 하나요? A:
- 물리 장치에 전원이 들어오고 네트워크에 연결되어 있는지 확인합니다.
- HA의 통합 페이지에서 Tuya를 찾아 점 세 개를 클릭하고 “다시 로드” (Reload)를 선택합니다.
- 그래도 안 되면 HomeAssistant를 재시작해 보세요.
Q: 앱에서 장치 이름을 바꿨는데 HA가 동기화되나요? A: 실시간으로 동기화되지 않습니다. HA의 Tuya 통합 페이지에서 “다시 로드”를 클릭해야 최신 장치 이름으로 업데이트됩니다.
