LG ThinQ SmartThings Edge Driver

2026년 07월 10일

LG ThinQ Connect 기기를 SmartThings에 연동하는 Edge Driver입니다. 브리지 서버의 /api/forward?url= 를 경유하여 ThinQ Connect REST API를 호출하고, ThinQ MQTT 메시지를 Edge Driver로 실시간 Push합니다.

아키텍처

LG ThinQ Cloud
      │  MQTT (상태 변경 실시간 Push)
      ▼
브리지 서버 (Python / aiohttp)
  /api/forward?url=         ← 기존 엔드포인트 (ThinQ REST API 명령 전달)
  /api/thinq/register       ← 신규 (Edge Driver 콜백 등록/해제)
  /api/thinq/endpoints      ← 신규 (등록 목록 조회, 디버그용)
      │  HTTP POST /thinq/event
      ▼
SmartThings Edge Driver (Lua)
  init.lua                  ← 드라이버 진입점, HTTP 이벤트 서버, 라이프사이클
  thinq_api.lua             ← ThinQ REST API 호출 모듈
  device_manager.lua        ← 기기 목록 동기화 모듈
      │
      ▼
SmartThings 앱 / 자동화

동작 흐름

[드라이버 시작]
  1. cosock TCP 서버 바인딩 (포트 자동 할당)
  2. POST /api/thinq/register { callbackUrl, pat, country }
  3. 브리지: ThinQApi 초기화 → 전체 기기 MQTT 구독
  4. 5분 주기 재등록으로 연결 유지

[ThinQ 기기 상태 변경]
  1. ThinQ Cloud → 브리지 MQTT 수신
  2. 브리지 → POST http://hub-ip:PORT/thinq/event
  3. Edge Driver process_thinq_event()
  4. SmartThings capability emit

[SmartThings 명령]
  1. SmartThings 앱 → Edge Driver handle_switch()
  2. Edge Driver → GET /api/forward?url=https://api-aic.lgthinq.com/devices/{id}/control
  3. ThinQ 기기 제어

파일 구성

thinq-edge-driver/
├── README.md
├── package.yaml
├── bridge_thinq.py           ← 브리지 서버 추가 모듈
├── profiles/
│   ├── setup.yaml            ← 허브 설정 기기 (PAT, 국가 코드, 브리지 서버)
│   ├── thinq-device.yaml     ← 범용 기기 (fallback)
│   ├── thinq-aircon.yaml     ← 에어컨
│   ├── thinq-washer.yaml     ← 세탁기 / 건조기 / 워시타워
│   ├── thinq-airpurifier.yaml
│   └── thinq-appliances.yaml ← 냉장고, 식기세척기, 온수기, 가습기, 로봇청소기
└── src/
    ├── init.lua              ← 드라이버 메인
    ├── thinq_api.lua         ← ThinQ REST API 모듈
    └── device_manager.lua    ← 기기 목록 동기화

설치 방법

1. 브리지 서버에 ThinQ 모듈 추가

# 기존 브리지 서버 app.py 에 추가
from bridge_thinq import setup_thinq_bridge

async def on_startup(app):
    await setup_thinq_bridge(app, app["session"])

async def on_cleanup(app):
    if app.get("thinq_bridge"):
        await app["thinq_bridge"].stop()

app.on_startup.append(on_startup)
app.on_cleanup.append(on_cleanup)

2. Edge Driver 배포

smartthings edge:drivers:package thinq-edge-driver/
smartthings edge:drivers:install <driver-id> --hub <hub-id>

3. SmartThings 앱에서 기기 추가

  1. SmartThings 앱 → + → 기기 추가 → 직접 추가
  2. LG ThinQ Connect 선택 → Discovery
  3. 허브 기기 생성 후 설정에서 입력:
    • 브리지 서버: http://192.168.x.x:8088
    • PAT 토큰: connect-pat.lgthinq.com 에서 발급
    • 국가 코드: KR
  4. Refresh 버튼 → ThinQ 기기 자동 동기화

API 규격

브리지 서버 API

기존 엔드포인트 (변경 없음)

GET /api/forward?url={thinq_api_url}

설명: ThinQ Connect REST API를 대신 호출하고 결과 반환.
     Authorization 등 헤더는 Edge Driver가 직접 포함하여 전달.

예시:
  GET /api/forward?url=https://api-aic.lgthinq.com/devices
  GET /api/forward?url=https://api-aic.lgthinq.com/devices/{deviceId}/status
  POST /api/forward?url=https://api-aic.lgthinq.com/devices/{deviceId}/control

신규 엔드포인트 (bridge_thinq.py 추가 시)

POST /api/thinq/register

Edge Driver가 드라이버 시작 시 콜백 URL을 등록합니다. 브리지는 등록 즉시 ThinQ MQTT에 연결하고 전체 기기를 구독합니다.

Request:

{
  "callbackUrl": "http://192.168.x.x:PORT",
  "pat"        : "eyJhbGci...",
  "country"    : "KR"
}

Response 200:

{
  "ok"         : true,
  "callbackUrl": "http://192.168.x.x:PORT"
}

Response 400:

{
  "error": "callbackUrl, pat 필수"
}

DELETE /api/thinq/register

Edge Driver 종료 또는 허브 기기 삭제 시 콜백을 해제합니다.

Request Body:

{
  "callbackUrl": "http://192.168.x.x:PORT"
}

또는 Query String:

DELETE /api/thinq/register?callbackUrl=http://192.168.x.x:PORT

Response 200:

{
  "ok": true
}

GET /api/thinq/endpoints

등록된 콜백 목록을 반환합니다. 디버깅용.

Response 200:

[
  {
    "callbackUrl"  : "http://192.168.x.x:PORT",
    "country"      : "KR",
    "registered_at": "2026-06-05T10:00:00"
  }
]

Edge Driver HTTP 서버 API

Edge Driver가 cosock으로 여는 내부 HTTP 서버입니다. 포트는 OS가 자동 할당하며, 브리지에 등록 시 callbackUrl로 전달됩니다.

POST /thinq/event

브리지가 ThinQ MQTT 메시지 수신 시 Edge Driver로 Push합니다.

Request (상태 변경):

{
  "deviceId"  : "TQSXXXX",
  "deviceType": "WASHER",
  "pushType"  : "DEVICE_PUSH_REPORT",
  "report"    : {
    "powerState": "POWER_ON",
    "runState"  : "RUNNING"
  }
}

Request (WashTower – report 키가 sub_id):

{
  "deviceId"  : "TQSXXXX",
  "deviceType": "WASHTOWER",
  "pushType"  : "DEVICE_PUSH_REPORT",
  "report"    : {
    "dryer": {
      "powerState": "POWER_ON"
    }
  }
}

Request (알림):

{
  "deviceId"  : "TQSXXXX",
  "deviceType": "WASHER",
  "pushType"  : "DEVICE_PUSH_NOTIFY",
  "pushCode"  : "WASHING_IS_DONE"
}

Response 200 (즉시 응답 후 처리):

{
  "ok": true
}

앞으로 해야 할 것

Phase 1 — 기본 동작 검증 (최우선)

  • 브리지 서버에 bridge_thinq.py 실제 통합 및 기동 확인
  • Discovery → 허브 기기 생성 → PAT 입력 → Refresh → ThinQ 기기 등록 흐름 테스트
  • MQTT 메시지 수신 및 Edge Driver capability emit 확인
  • SmartThings 앱에서 switch ON/OFF 명령 → ThinQ 기기 반응 확인
  • 5분 재등록 루프 정상 동작 확인

Phase 2 — 안정성 강화

  • 브리지 서버 재시작 시 Edge Driver 자동 재등록 처리
    • 현재: 5분 재등록 루프로 커버되나 최대 5분 공백 발생
    • 개선: 브리지가 재시작 시 등록된 callbackUrl로 재연결 알림 전송
  • MQTT 연결 끊김 시 브리지 자동 재연결 로직 검증
  • ThinQ API 호출 실패 시 재시도 처리 (rate limit 대응)
  • 허브 기기 삭제 시 자식 ThinQ 기기 일괄 삭제 검증

Phase 3 — 기기별 capability 확장

  • 에어컨 — 온도 설정 (thermostatCoolingSetpoint), 모드, 풍량
  • 공기청정기 — PM2.5/PM10 (dustSensor), 공기질 (airQualitySensor)
  • 냉장고 — 냉장/냉동 온도, 도어 열림 (contactSensor)
  • 세탁기/건조기 — 운전 상태, 잔여 시간
  • 온수기 — 설정 온도, 현재 온도
  • 로봇청소기 — 배터리, 청소 상태
  • WashTower — dryer/washer sub_id 분리 처리 검증

Phase 4 — 사용성 개선

  • 기기 동기화 시 이미 등록된 기기 label 자동 갱신
  • ThinQ 기기 삭제(앱에서 해제) 시 SmartThings 기기도 자동 삭제
  • 알림(DEVICE_PUSH_NOTIFY) — SmartThings 알림 capability 연동
  • 에너지 사용량 API 연동 (energyMeter)

참고

항목URL
ThinQ Connect APIhttps://api-aic.lgthinq.com
PAT 발급https://connect-pat.lgthinq.com
SmartThings CLIhttps://github.com/SmartThingsCommunity/smartthings-cli
Edge Driver 개발 가이드https://developer.smartthings.com/docs/edge-device-drivers

AI, SmartThings, 정보