Home Assistant(HA)에 Tesla를 연동하는 것은 매우 인기 있는 기능이지만, Tesla 공식 API가 자주 변경되기 때문에(특히 2024년에 Fleet API와 더 엄격한 인증 체계가 도입된 이후) 공식 Tesla 통합은 정상적으로 작동하지 않는 경우가 많습니다.
현재 가장 안정적이고 기능이 가장 완전한 방법은 HACS(Home Assistant Community Store)를 통해 서드파티 Tesla Custom Integration을 설치하는 것입니다.
아래는 2024/2025년 기준 최신 상세 튜토리얼입니다.
사전 준비
- Home Assistant가 설치되어 정상적으로 실행 중이어야 합니다.
- HACS(통합 스토어)가 설치되어 있어야 합니다.
- HACS를 아직 설치하지 않았다면 먼저 “Home Assistant HACS 설치” 튜토리얼을 검색해 보세요. HA를 다루는 데 필수적인 도구입니다.
Tesla 계정(이메일과 비밀번호).
Token을 얻는 도구(아래에서 설명합니다. 비밀번호로 직접 로그인할 수는 없습니다).
1단계: Tesla Custom Integration 설치 (HACS 사용)
HA에 내장된 “Tesla” 통합은 사용하지 마세요. 그것은 대부분 작동하지 않습니다. 우리는 alandtse가 유지 관리하는 버전을 사용합니다.
- Home Assistant 왼쪽 메뉴에서 HACS를 엽니다.
- Integrations(통합)를 클릭합니다.
- 오른쪽 아래의 Explore & Download Repositories(저장소 탐색 및 다운로드)를 클릭합니다.
- 검색창에 Tesla를 입력합니다.
- Tesla Custom Integration을 찾습니다(작성자는 보통 alandtse 또는 비슷하게 표시되니 잘못 선택하지 마세요).
- 클릭해서 들어간 뒤 오른쪽 아래의 Download(다운로드)를 클릭합니다.
- 다운로드가 끝나면 Home Assistant를 재시작합니다(설정 -> 시스템 -> 다시 시작).
2단계: Refresh Token(리프레시 토큰) 얻기
Tesla가 복잡한 검증(MFA/인증 코드)을 켜 두었기 때문에 HA에 계정과 비밀번호를 직접 입력하면 보통 실패합니다. 먼저 외부에서 Refresh Token을 생성해야 합니다.
Token을 안전하게 얻으려면 다음 서드파티 앱을 권장합니다(이 앱들은 Tesla API 토큰 생성 전용입니다):
- Android 사용자: Tesla Tokens를 다운로드하세요(Play Store 또는 GitHub에서 검색).
- iOS / macOS 사용자: Auth for Tesla를 다운로드하세요(App Store에서 검색).
- 범용 웹 버전(앱이 불안하다면): 오픈소스 Token 생성 스크립트를 사용할 수도 있지만, 현재는 앱이 가장 편리합니다.
작업 단계:
- 위 앱을 엽니다.
- Tesla 계정으로 로그인합니다.
- 로그인에 성공하면 앱이 문자열을 생성합니다.
- Refresh Token(리프레시 토큰)을 찾아 복사합니다.
- 주의: Token은 매우 긴 문자열이므로 반드시 끝까지 복사하세요.
3단계: Home Assistant에서 통합 구성하기
- HA가 재시작을 완료했는지 확인합니다.
- 왼쪽 메뉴에서 설정(Settings) -> 기기 및 서비스(Devices & Services)를 클릭합니다.
- 오른쪽 아래의 통합 추가(Add Integration)를 클릭합니다.
- Tesla Custom Integration을 검색합니다(주의: “Tesla”로 표시될 수 있으며 아이콘은 보통 빨간색 T입니다. 방금 HACS로 설치한 것인지 반드시 확인하세요. 목록에 Tesla가 두 개 있다면 보통 “Custom” 표시가 있는 것 또는 위에 있는 것을 선택하고, 하나만 있다면 그냥 클릭하세요).
- 나타나는 구성 창에서:
- Email: Tesla 계정 이메일을 입력합니다.
- Refresh Token: 2단계에서 얻은 긴 문자열을 붙여 넣습니다.
- Access Token(선택): 보통 입력할 필요가 없으며 비워 두면 됩니다.
- URL Proxy(선택): 직접 만든 Fleet API 프록시가 없다면 비워 둡니다.
제출(Submit)을 클릭합니다.
모든 것이 순조롭다면 HA가 Tesla 서버에 연결하고 차량을 어느 “지역”에 배치할지 선택하라는 메시지를 표시합니다. 완료하면 새 기기(차량 이름)가 표시됩니다.
4단계: 기능 확인과 엔티티 소개
구성에 성공하면 “기기 및 서비스”에서 Tesla를 찾아 “기기”로 들어가면 수십 개의 엔티티가 보입니다.
자주 쓰는 엔티티는 다음과 같습니다:
- Binary Sensor(바이너리 센서):
- binary_sensor.tesla_online: 차량이 온라인인지 여부(깨어 있는 상태).
- binary_sensor.tesla_charging: 충전 중인지 여부.
- binary_sensor.tesla_parking_brake: 주차 브레이크 상태.
Sensor(센서):
- sensor.tesla_battery_level: 배터리 퍼센트.
- sensor.tesla_range: 남은 주행 거리.
- sensor.tesla_charging_rate: 충전 속도.
- sensor.tesla_location: 차량 위치(지도 추적용).
- sensor.tesla_inside_temperature: 실내 온도.
Switch(스위치 – 제어 가능):
- switch.tesla_charger: 충전 시작/중지.
- switch.tesla_sentry_mode: 센트리 모드 스위치.
- switch.tesla_heated_steering_wheel: 스티어링 휠 히터.
Lock(잠금):
- lock.tesla_door_lock: 도어 잠금 제어.
Climate(공조):
- climate.tesla_hvac_climate_system: 공조 켜기/끄기, 온도 설정.
5단계: 핵심 설정 – 차량의 “불면증” 방지 (전력 소모 문제)
이것이 가장 중요한 단계입니다! 설정을 잘못하면 HA가 계속 차량 상태를 조회해서 차량이 잠들지 못하고 심각한 뱀파이어 드레인(대기 전력 소모)이 발생합니다.
- Tesla 통합 페이지에서 내 기기를 클릭하고 구성(Configure) 버튼을 찾습니다(또는 통합 목록 페이지에서 “옵션”을 클릭합니다).
- Enable Polling(폴링 활성화):
- 기본적으로 이 통합은 스마트 폴링을 시도합니다.
- Active polling(능동 폴링) 옵션의 설정을 체크하는 것을 권장하지만 신중하게 하세요.
강력히 권장하는 설정:
- Polling Policy(폴링 정책): 차량이 잠들어 있을 때 HA가 강제로 깨우지 않도록 하세요.
- 보통 통합이 자동으로 처리합니다: binary_sensor.tesla_online이 Off가 되면 HA는 명령 전송을 멈추고, 사용자가 수동으로 스위치(공조 켜기 등)를 작동하거나 차량이 스스로 깨어날 때(문을 열 때 등)까지 기다립니다.
- 통합 옵션에서 Wake Up 정책을 설정할 수 있습니다. HA로 언제든 차량을 제어할 필요가 없다면 “자동 깨우기”를 끄는 것을 권장합니다.
모범 사례:
- 매분 배터리를 확인하는 자동화를 만들지 마세요.
- HA의 button.tesla_wake_up 엔티티를 활용하세요. 차량을 조작해야 할 때(예: 아침 8시에 공조를 켜는 자동화)는 “공조 켜기” 서비스를 호출하기 전에 “차량 깨우기” 서비스를 먼저 호출하고 몇 초 기다린 뒤 명령을 보내세요.
고급: 자동화 만드는 방법 (예시)
시나리오: 태양광 패널의 잉여 전력이 생길 때 자동 충전하거나, 심야 저렴한 전기 요금으로 충전하기.
- 트리거 조건: 시간이 밤 10:00(저렴한 요금 시작).
- 환경 조건: 차량이 집에 있고(device_tracker.tesla_location이 Home 영역에 있음) 충전 케이블이 꽂혀 있음(binary_sensor.tesla_charger_sensor가 Connected).
- 동작:
- 서비스 호출: switch.turn_on -> 대상: switch.tesla_charger.
시나리오: 여름에 외출 전 자동으로 실내 온도 낮추기.
- 트리거 조건: 휴대폰 알람이 멈춤(Android인 경우) 또는 시간이 오전 8:00에 도달.
- 동작:
- 서비스 호출: climate.set_temperature -> 대상: Tesla 공조 -> 온도: 22도.
- 서비스 호출: climate.set_hvac_mode -> 모드: Heat/Cool.
자주 발생하는 문제와 문제 해결
- 401 / 403 오류 (Authentication Failed):
- Refresh Token이 만료되었습니다. 앱으로 새 Token을 다시 생성한 뒤 HA 통합 페이지에서 “재구성”을 클릭해 새 Token을 입력하세요.
차량이 계속 잠들지 않음:
- 다른 서드파티 앱(TeslaFi, Tessie 등)도 자주 접근하고 있는지 확인하세요.
- HA 통합 옵션에서 “Wake up on start”(시작 시 깨우기)를 끄세요.
제어 지연:
- 이것은 정상입니다. 차량이 잠들어 있으면 명령을 보내기 위해 먼저 차량을 깨워야 하며(약 15~30초), 그 후에 동작이 실행됩니다.
API 제한 (Fleet API):
- Tesla는 이제 API 호출 횟수에 제한을 두고 있습니다. 전혀 제어할 수 없다면 그날의 호출 횟수를 초과한 것일 수 있으며, 하루 쉬면 보통 자동으로 복구됩니다.
이 튜토리얼이 Tesla를 Home Assistant에 연동하는 데 도움이 되기를 바랍니다!
작성자 소개 — Laite Intelligent는 2010년 설립되어 스마트홈 토탈 솔루션을 전문으로 합니다. Now ALL IN HA.
