Homebridge SmartThings ACs

homebridge-smartthings-acs는 SmartThings 에어컨을 HomeKit에 연동하고, 웹훅(Webhook)을 통한 실시간 상태 업데이트를 지원하는 고성능 Homebridge 플러그인입니다.

핵심 기능

• 실시간 상태 동기화 (웹훅): SmartThings 앱이나 다른 방법으로 에어컨 상태를 변경하면, 웹훅을 통해 거의 즉시 HomeKit에 상태가 반영됩니다.
• 안전하고 영구적인 인증 (OAuth 2.0): 한 번의 설정으로 토큰이 자동 갱신되는 안정적인 인증 방식을 사용합니다.
• 다중 디바이스 지원: 여러 대의 에어컨을 config.json에 등록하여 한 번에 관리할 수 있습니다.
• 장치별 기능 선택: config.json에서 각 에어컨 모델이 지원하는 부가 기능(무풍, 자동 건조 등)을 선택적으로 활성화할 수 있습니다.
• 안정적인 API 통신: API 요청 재시도 및 동시성 제어 로직이 포함되어 안정적인 통신을 보장합니다.
• GUI 설정 지원: Homebridge UI 환경에서 설정을 쉽게 입력하고 관리할 수 있습니다.

사전 준비

1. Homebridge: Homebridge가 설치되어 있어야 합니다.
2. Node.js: v18.0.0 이상 버전이 필요합니다.
3. 공개 접속 가능 주소 및 리버스 프록시: (필수) SmartThings 서버가 외부에서 Homebridge 서버로 접속할 수 있는 https 기반의 공개 주소가 필요하며, 이 주소를 내부 http 서버로 전달해 줄 리버스 프록시(Reverse Proxy) 설정이 완료되어 있어야 합니다.
4. SmartThings CLI: 아래 설치 과정에서 필요합니다.

설치

Homebridge UI의 '플러그인' 탭에서 homebridge-smartthings-acs를 검색하여 설치하거나, 터미널에서 아래 명령어를 직접 실행합니다.

npm install -g homebridge-smartthings-acs

설정 가이드 (리버스 프록시 필수)

이 플러그인은 리버스 프록시 사용을 전제로 설계되었습니다.

• 외부 주소 (리버스 프록시 Source): https://<나의도메인>:<외부포트>
• 내부 주소 (리버스 프록시 Destination): http://<홈브릿지IP>:8999

플러그인은 내부적으로 항상 8999 포트에서만 요청을 기다립니다.

1단계: SmartThings OAuth App 생성

플러그인 설정에 필요한 clientId와 clientSecret을 발급받습니다. 이 과정은 최초 한 번만 필요합니다.

1. SmartThings CLI 설치 및 인증

• 터미널에서 npm install -g @smartthings/cli를 실행하여 CLI를 설치합니다.
• SmartThings 개인용 액세스 토큰 페이지에서 모든 권한을 가진 PAT를 발급받습니다.
• 터미널에서 export SMARTTHINGS_TOKEN="YOUR_PAT_TOKEN" 명령어로 인증합니다.

2. OAuth App 생성

• 터미널에서 smartthings apps:create를 실행하고 대화형 프롬프트를 따릅니다.
• Choose an app type: WEBHOOK_SMART_APP을 선택합니다.
• Display Name: 앱의 이름입니다. (예: Homebridge ACs)
• Target URL: (중요) 리버스 프록시로 설정한 외부 https 주소를 입력합니다. 이 주소는 웹훅 수신에 사용됩니다.
  • 예시: https://myhome.myds.me:9001 (경로가 있다면 경로까지 포함)
• Select Scopes: 스페이스바를 눌러 r:devices:* 와 x:devices:* 권한을 모두 선택하고 엔터를 누릅니다.
• Add or edit Redirect URIs: Add Redirect URI를 선택하고, 위 Target URL과 동일한 주소를 입력합니다.

모든 절차가 완료되면, 터미널에 OAuth Client Id와 OAuth Client Secret 값이 출력됩니다. 이 값을 복사하여 다음 단계에서 사용합니다.

2단계: Homebridge config.json 설정

{
  "platform": "SmartThingsACs",
  "name": "SmartThings ACs",
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET",
  "redirectUri": "[https://myhome.myds.me:9001](https://myhome.myds.me:9001)",
  "devices": [
    {
      "deviceLabel": "거실 에어컨",
      "model": "AF19B7934WZT",
      "serialNumber": "AC-SERIAL-001",
      "enableWindFree": false,
      "enableAutoClean": false
    },
    {
      "deviceLabel": "안방 에어컨",
      "enableWindFree": true,
      "enableAutoClean": true
    }
  ]
}

• redirectUri: 1단계에서 Target URL 및 Redirect URI로 등록한 외부 https 공개 주소를 정확히 동일하게 입력합니다.
• devices: 홈킷에 추가할 에어컨 목록입니다.
  • deviceLabel: SmartThings 앱에 표시되는 에어컨의 이름과 정확히 일치해야 합니다.
  • model, serialNumber: 홈 앱에 표시할 모델명과 일련번호 (선택 사항).
  • enableWindFree, enableAutoClean: 해당 에어컨 모델이 API를 통해 무풍, 자동건조 기능을 지원하는 경우에만 체크(true)합니다.

3단계: 플러그인 최초 인증

1. 설정 저장 후 Homebridge를 재시작합니다.
2. 로그에 표시된 [스마트싱스 인증 필요] 메시지와 인증 URL을 확인합니다.
3. 인증 URL 전체를 복사하여 웹 브라우저에 붙여넣고 접속합니다.
4. SmartThings 계정으로 로그인하고, 생성한 앱에 대한 권한을 '허용(Authorize)' 합니다.
5. "인증 성공!" 메시지 확인 후 Homebridge를 다시 한번 재시작하면 모든 설정이 완료됩니다.