이 글에서는 Tuya 생태계가 어떻게 작동하는지부터, 오픈소스 도구 TinyTuya의 Wizard 기능으로 이 두 값을 추출하는 전 과정, 그리고 실제로 삽질하며 겪게 되는 트러블슈팅 팁까지 한 번에 정리했습니다.

    Tuya 스마트홈 플랫폼


    Tuya Smart(투야)는 조명, 플러그, 스위치, 센서 같은 스마트 기기를 만드는 제조사들이 하드웨어부터 클라우드 서버, 앱까지 직접 개발하지 않아도 되도록 지원하는 글로벌 IoT PaaS/SaaS 플랫폼입니다.

    제조사는 Tuya의 모듈과 클라우드, 앱 솔루션만 탑재하면 빠르게 제품을 "스마트화"할 수 있습니다.
    이 덕분에 전 세계 수천 개 브랜드의 기기가 실제로는 같은 Tuya 인프라 위에서 동작하고 있습니다. 겉보기엔 전혀 다른 브랜드의 스마트 플러그라도, 뜯어보면 같은 Tuya 생태계 안에서 호환되는 경우가 매우 많은 이유가 여기에 있습니다. 

    Tuya Smart 와 Smart Life


    Tuya의 공식 모바일 앱인 Tuya Smart와 Smart Life는 기능과 UI 측면에서 사실상 동일한 앱입니다. 두 앱 모두 같은 Tuya 클라우드 백엔드를 공유하며, Tuya 개발자 계정과 연동(Link App Account)할 수 있다는 점도 동일합니다.

    개인이 집에서 다양한 브랜드의 스마트 기기를 함께 쓰고 구글홈·시리 등과 연동하고 싶다면 Smart Life 앱을 쓰는 편이 무난합니다. 이후 진행할 TinyTuya 설정 과정도 Smart Life 앱을 기준으로 안내합니다.

    구분 Tuya SmartSmart Life
    타겟 B2B 솔루션 검증 / 공식 브랜드 일반 사용자 B2C 스마트홈 구축
    특징 Tuya 플랫폼 관련 B2B 서비스 연결에 용이 IFTTT, Siri 단축어 등 제3자 서비스 연동 지원 범위가 넓음
    대상 Tuya 전용 인프라를 사용하는 브랜드/개발자 일반적인 스마트홈 구성 및 제3자 플랫폼 연동

    Smart Life

    TinyTuya 란 무엇인가?


    TinyTuya는 Tuya Wi-Fi 기반 디바이스를 Tuya 클라우드를 거치지 않고 로컬 네트워크(LAN)에서 직접 제어·모니터링할 수 있게 해주는 오픈소스 Python 라이브러리 겸 CLI 도구입니다. 

    2020년 Jason A. Cox가 개발해 PyPI에 공개한 이후, Home Assistant의 LocalTuya 연동이나 개인 Python 스크립트로 스마트 기기를 제어할 때 사실상 표준처럼 쓰이고 있습니다
    .
    클라우드를 거치지 않는다는 것은 곧 다음을 의미합니다.
    • 응답 속도 향상 - 클라우드 왕복 없이 소켓 통신으로 즉시 제어되므로 체감 반응 속도가 훨씬 빠릅니다.
    • 인터넷 장애에도 동작 - 공유기와 기기만 살아있으면 인터넷이 끊겨도 로컬 제어가 가능합니다.
    • 프라이버시 - 기기 상태 데이터가 외부 클라우드로 나가지 않습니다.
    TinyTuya는 라이브러리 기능 외에도 내장 네트워크 스캐너(`python -m tinytuya scan`)를 제공해 LAN 상의 Tuya 기기 주소와 버전을 바로 확인할 수 있고, 최근 버전에서는 `python -m tinytuya devices`, `python -m tinytuya snapshot` 같은 대화형 명령도 추가되었습니다. 

    다만 스캔만으로는 기기를 제어할 수 없고, 실제 제어를 위해서는 아래에서 다룰 Local Key가 반드시 필요합니다.

    Local Key가 반드시 필요한 이유

    Tuya 기기는 로컬 제어 시 보안을 위해 모든 통신을 암호화합니다. 이 암호화를 해제하고 실제 명령(켜기/끄기, 밝기 조절 등)을 내리려면 각 디바이스 고유의 Local Key와 Device ID가 반드시 필요합니다.

    문제는 이 Local Key가 Tuya 앱 화면 어디에도 그냥 노출되어 있지 않다는 점입니다. Tuya는 이 값을 Tuya IoT 개발자 플랫폼을 통해서만 조회할 수 있도록 설계해 두었고, 그래서 TinyTuya의 Wizard 기능이 필요합니다. Wizard는 개발자 계정의 API 인증 정보로 Tuya 클라우드에 질의해, 사용자가 앱에 등록해 둔 모든 기기의 Local Key를 한 번에 긁어옵니다.

    기기를 앱에서 삭제 후 다시 페어링(재등록)하거나 펌웨어를 업데이트하면 Local Key가 자동으로 재발급되어 바뀝니다. 이 경우 Wizard를 다시 실행해 새 Key를 받아야 합니다.

    Tuya Wizard

    Tiny Wizard는 TinyTuya 라이브러리 내에 포함 되어 있는 핵심 연동 기능입니다. 로컬 키를 Tuya 개발자 클라우드 플랫폼에서 자동으로 추출하여 컴퓨터에 저장해주는 기능을 합니다.

    Tuya Wizard로 Device ID / Local Key 추출하기


    Tuya Wizard는 링크에서 다운로드 받으실 수 있습니다.

    1단계. Smart Life 앱에 기기 등록하기

    Smart Life 또는 Tuya Smart 앱을 설치하고, 제어하려는 모든 Tuya 디바이스를 정식 계정으로 페어링합니다. 임시 게스트 계정이 아닌 정식 계정을 반드시 사용해야 합니다. 게스트 계정으로 진행하면 이후 단계에서 예고 없이 연결이 끊길 수 있습니다.

    2단계. Tuya Wizard 실행

    1. 다운로드 받은 파일 압축을 풀고 실행합니다. 
    2. 코드를 입력해야합니다. 코드는 Smart Life 앱 상단에 '설정'을 누르고 '계정 및 보안'을 누르면 사용자 코드를 확인할 수 있습니다.
    3. QR 코드가 뜨면 Smart Life 앱 상단에 QR 리더를 눌러 QR 코드를 읽습니다.
    4. 홈 어시스턴트 로그인합니다.
    5. device.json 파일이 같은 폴더 안에 저장됩니다. json 파일 안에 ip주소, Device ID(id)이고 Local Key, version(프로토콜)을 확인할 수 있습니다.
    tuya wizard