# Homebridge Samsung AC (구형 모델 / Legacy Model) 구형 삼성 에어컨(TLSv1 통신 방식)을 Apple HomeKit에 연동하기 위한 Homebridge **플랫폼** 플러그인입니다. 이 플러그인은 최신 Node.js(v17 이상) 환경에서 발생하는 TLS 호환성 문제를 해결하기 위한 패치를 포함하고 있습니다. 또한, **인증서가 플러그인에 내장**되어 있어 사용자는 더 이상 `.pem` 파일을 직접 구하거나 경로를 설정할 필요 없이, 오직 **IP 주소와 토큰만으로** 플러그인을 설정할 수 있습니다. **플랫폼(Platform)** 방식으로 전환되어, 불안정한 에어컨 장치를 **자식 브릿지(Child Bridge)**에 격리하여 홈브릿지 전체의 안정성을 확보할 수 있습니다. ## 주요 기능 ✨ * **구형 삼성 에어컨 지원**: TLSv1 통신 프로토콜을 사용하는 모델 지원 * **최신 Homebridge 호환**: Node.js v17, v18, v22 등 최신 버전에서 발생하는 모든 TLS/HTTP 오류 해결 * **안정성 확보**: **자식 브릿지** 지원으로, 에어컨의 응답 없음 문제가 다른 액세서리에 영향을 주지 않도록 격리 가능 * **인증서 내장**: 별도의 `.pem` 파일 설정이 필요 없어 설정이 매우 간편함 * **UI 설정 지원**: Homebridge UI를 통해 모든 설정을 간편하게 구성 가능 * **안정적인 통신**: 상태 캐싱, 자동 재시도, 주기적인 상태 폴링 기능 포함 ## 사전 준비 checklist * Homebridge 최신 버전 (UI 환경 권장) * 에어컨의 고정 IP 주소 * Python 3 및 OpenSSL (Homebridge가 설치된 환경이라면 대부분 이미 설치되어 있습니다) * **공유기 관리자 페이지 접근 권한** (DNS 설정 변경을 위해 필요) ## 설치 💻 Homebridge UI의 '플러그인' 탭에서 `homebridge-samsung-ac`을 검색하여 설치합니다. --- ## 🔑 에어컨 토큰(Token) 추출 방법 (필수 절차) 이 플러그인을 사용하려면 에어컨의 고유 인증 토큰이 필요합니다. 토큰은 **DNS 스푸핑(Spoofing)**이라는 기법을 사용하여, 에어컨이 삼성 클라우드 서버(`api.smartthings.com`)와 통신하는 내용을 중간에서 가로채어 추출합니다. ### **1단계: 가짜 서버 스크립트 준비** 1. 아래의 Python 코드를 복사하여 컴퓨터(또는 Homebridge가 설치된 NAS/라즈베리파이)에 `fake_server.py` 라는 이름으로 저장합니다. 이 스크립트는 에어컨의 통신을 받아낼 가짜 서버 역할을 합니다. ```python #!/usr/bin/env python3 import ssl import socket import os import threading # 설정 LISTEN_IP = '0.0.0.0' # 모든 IP에서 들어오는 연결을 수신 HTTPS_PORT = 443 CERT_FILE = 'temp_server_cert.pem' KEY_FILE = 'temp_server_key.pem' def generate_self_signed_cert(cert_file, key_file): """임시 SSL 서버 인증서 생성""" if not (os.path.exists(cert_file) and os.path.exists(key_file)): print(f"임시 서버 인증서 '{cert_file}' 및 '{key_file}' 생성 중...") # openssl이 설치되어 있어야 함 subj = "/CN=api.smartthings.com" os.system(f'openssl req -new -newkey rsa:2048 -days 365 -nodes -x509 -keyout {key_file} -out {cert_file} -subj "{subj}"') print("임시 서버 인증서 준비 완료.") def handle_client(conn, addr): """클라이언트 연결 처리 및 데이터 출력""" print(f"\n>>> [연결 수립] From: {addr}") try: while True: data = conn.recv(8192) if not data: break decoded_data = data.decode('utf-8', errors='ignore') print("\n" + "="*20 + " 데이터 수신 " + "="*20) print(decoded_data) # 'Authorization' 헤더에서 토큰 찾기 for line in decoded_data.splitlines(): if 'authorization' in line.lower(): print("\n" + "*"*20 + " 🎉 토큰 발견! 🎉 " + "*"*20) token = line.split(' ')[-1] print(f"추출된 토큰: {token}") print("*"*56) print("이 토큰을 복사하여 Homebridge 설정에 사용하세요.") # 에어컨에 정상적인 HTTP 응답을 보내줘야 연결 절차가 완료됨 conn.sendall(b'HTTP/1.1 200 OK\r\n\r\n') except Exception as e: print(f"[오류] 클라이언트 처리 중 오류: {e}") finally: print(f"<<< [연결 종료] From: {addr}") conn.close() def main(): """가짜 서버를 실행하여 토큰을 수신하고 출력""" generate_self_signed_cert(CERT_FILE, KEY_FILE) context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH) context.load_cert_chain(certfile=CERT_FILE, keyfile=KEY_FILE) with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock: sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) sock.bind((LISTEN_IP, HTTPS_PORT)) sock.listen(5) print("\n" + "="*50) print(f"가짜 삼성 클라우드 서버가 시작되었습니다. (포트: {HTTPS_PORT})") print("이제 에어컨을 Wi-Fi 설정 모드로 변경하고, SmartThings 앱으로 연결을 시도하세요.") print("="*50) while True: conn, addr = sock.accept() threading.Thread(target=handle_client, args=(conn, addr)).start() if __name__ == '__main__': try: main() except PermissionError: print("\n[오류] 443 포트를 사용하려면 root 권한이 필요합니다. 'sudo python3 fake_server.py'로 실행해주세요.") except KeyboardInterrupt: print("\n서버를 종료합니다.") finally: # 종료 시 임시 인증서 파일 삭제 if os.path.exists(CERT_FILE): os.remove(CERT_FILE) if os.path.exists(KEY_FILE): os.remove(KEY_FILE) ``` ### **2단계: DNS 스푸핑 설정 (가장 중요!)** 1. **스크립트 실행 컴퓨터의 IP 주소 확인:** `fake_server.py`를 실행할 컴퓨터(NAS, 라즈베리파이 등)의 **내부 IP 주소를 확인**합니다. (예: `192.168.1.10`) 2. **공유기 관리자 페이지 접속:** 웹 브라우저에서 공유기 관리자 페이지(보통 `192.168.0.1` 또는 `192.168.1.1`)에 접속합니다. 3. **DNS 설정 메뉴 찾기:** '고급 설정'의 'LAN 설정' 또는 'DNS' 관련 메뉴에서 **'정적 DNS(Static DNS)', 'DNS 호스트 이름(Hostname)'** 과 같은 기능을 찾습니다. (공유기 제조사마다 메뉴 이름이 다를 수 있습니다) 4. 아래 내용을 입력하고 저장/적용합니다. 이 설정은 `api.smartthings.com`으로 가야 할 에어컨의 요청을 우리 컴퓨터로 오게 만듭니다. * **호스트 이름 / 도메인 이름:** `api.smartthings.com` * **IP 주소:** 위에서 확인한 **스크립트 실행 컴퓨터의 IP 주소** (예: `192.168.1.10`) ![공유기 DNS 설정 예시](https://i.imgur.com/u5jJmYQ.png) ### **3단계: 토큰 추출 실행** 1. **가짜 서버 실행:** 터미널(PuTTY 등)에서 `fake_server.py` 파일이 있는 폴더로 이동 후, **root 권한**으로 스크립트를 실행합니다. (443번 포트 사용을 위해 root 권한 필요) ```bash sudo python3 fake_server.py ``` 2. **에어컨 연결 시도:** 에어컨을 **Wi-Fi 설정 모드**로 변경하고, **SmartThings 앱**을 사용하여 네트워크 연결 절차를 진행합니다. 3. **토큰 확인:** 에어컨이 Wi-Fi에 연결된 후 삼성 서버와 통신을 시도하면, DNS 설정 때문에 우리 PC의 가짜 서버로 접속하게 됩니다. 이때, 터미널 화면에 에어컨이 보낸 데이터와 함께 **`추출된 토큰: XXXXXXXX`** 이 출력됩니다. 4. **설정 원복:** 토큰을 성공적으로 얻었다면, 터미널에서 `Ctrl + C`를 눌러 가짜 서버를 종료하고, **반드시 2단계에서 변경했던 공유기의 DNS 설정을 삭제하여 원상 복구**해야 합니다. 그렇지 않으면 인터넷 사용에 문제가 생길 수 있습니다. --- ## 설정 ⚙️ Homebridge UI의 플러그인 설정 화면에서 '에어컨 추가' 버튼을 눌러 각 장치를 설정합니다. | 키 | 설명 | 기본값 | 필수 | | :--- | :--- | :--- | :--- | | `name` | 홈 앱에 표시될 에어컨의 이름 | - | **예** | | `ip` | 에어컨의 고정 IP 주소 | - | **예** | | `token`| 위에서 추출한 인증 토큰 | - | **예** | | `deviceIndex` | 상태를 **읽어올** 장치의 인덱스(0부터) | `0` | 아니오 | | `setDeviceIndex`| 명령을 **보낼** 장치의 인덱스 | `deviceIndex` | 아니오 | | `swingModeType` | 스윙(회전) 기능을 제어할 명령어 타입 | `comfort` | 아니오 | | `pollingInterval`| 상태 동기화 간격(초). 0이면 비활성화 | - | 아니오 | | `timeout`| 요청 응답 대기 시간(ms) | `5000` | 아니오 | | `cacheDuration`| 상태 정보 캐시 유지 시간(ms) | `30000` | 아니오 | | `debug` | 상세 로그 활성화. 문제 해결 시 사용 | `false` | 아니오 | | `minTemp` | 설정 가능한 최저 온도 (°C) | `18` | 아니오 | | `maxTemp` | 설정 가능한 최고 온도 (°C) | `30` | 아니오 | | `manufacturer`| 홈 앱에 표시될 제조사 이름 | `Samsung` | 아니오 | | `model`| 홈 앱에 표시될 모델명 | `AC-Model` | 아니오 | | `serialNumber`| 홈 앱에 표시될 시리얼 번호 | `(이름과 동일)`| 아니오 | #### `config.json` 직접 수정 예시 ```json { "bridge": { "...": "..." }, "platforms": [ { "platform": "SamsungACPlatform", "name": "Samsung ACs", "accessories": [ { "name": "거실 에어컨", "ip": "192.168.1.50", "token": "YOUR-EXTRACTED-TOKEN-HERE", "pollingInterval": 30, "debug": false, "minTemp": 18, "maxTemp": 30 }, { "name": "침실 에어컨", "ip": "192.168.1.51", "token": "ANOTHER-TOKEN-HERE", "pollingInterval": 30 } ] } ] } ``` 🚀 안정성을 위한 자식 브릿지(Child Bridge) 설정 (강력 추천) 에어컨의 응답 없음 문제가 다른 액세서리에 영향을 주지 않도록, 이 플러그인을 자식 브릿지에서 실행하는 것을 강력히 권장합니다. 플러그인 설정 이동: 홈브릿지 UI의 '플러그인' 탭에서 Homebridge Samsung Ac을 찾습니다. 설정 아이콘 클릭: 플러그인 우측의 공구 모양(설정) 아이콘을 클릭합니다. 브릿지 설정: 팝업 메뉴에서 **'브릿지 설정(Bridge Settings)'**을 선택합니다. 자식 브릿지로 실행: '별도의 자식 브릿지에서 실행(Run in a separate Child Bridge)' 옵션을 켭니다. 저장 및 재시작: 설정을 **저장(Save)**하고, 홈브릿지를 재시작하면 완료됩니다. ⚠️ 보안 경고 이 플러그인은 오래된 보안 프로토콜(TLSv1)을 사용하여 에어컨과 통신합니다. 신뢰할 수 있는 로컬 네트워크 환경에서만 사용하시는 것을 강력히 권장합니다.