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 라는 이름으로 저장합니다. 이 스크립트는 에어컨의 통신을 받아낼 가짜 서버 역할을 합니다.

   #!/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)

   

3단계: 토큰 추출 실행

1. 가짜 서버 실행: 터미널(PuTTY 등)에서 fake_server.py 파일이 있는 폴더로 이동 후, root 권한으로 스크립트를 실행합니다. (443번 포트 사용을 위해 root 권한 필요)

   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 직접 수정 예시

{
  "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)을 사용하여 에어컨과 통신합니다. 신뢰할 수 있는 로컬 네트워크 환경에서만 사용하시는 것을 강력히 권장합니다.