Repository navigation
LG_THINQ_INTEGRATION
LG ThinQ 가전(공기청정기 등)을 Home Assistant(HA)에 연결하고, 외부 클라이언트가 HA REST API로 상태를 읽고 제어하는 절차를 정리한 실무 가이드다. 실측 예시는
appStore/tablet-fe/ha-api.http(VS Code REST Client 파일) 기준이며, 본문 요청 번호(#0~#8)는 그 파일의 요청 번호와 일치한다. 본 문서는 논의/온보딩용 자료다. HA가 시스템에서 갖는 역할(상태 저장소)은 OSS_INTEGRATION.md, HA·MQTT 기초는 ROBOT_ADAPTER_ONBOARDING.md를 참고한다.
LG ThinQ 가전 ──(Wi-Fi)──▶ LG ThinQ Cloud
▲
│ ThinQ Connect API (LG PAT 토큰)
▼
Home Assistant ← LG ThinQ integration 이 기기를 엔티티로 흡수
▲
│ REST API /api/* (Bearer HA_TOKEN)
▼
클라이언트 (ha-api.http · BFF · 스크립트 등)
- 토큰이 두 종류다. ① LG PAT(Personal Access Token): HA ↔ ThinQ Cloud 연결용, LG 계정에서 발급. ② HA Long-Lived Access Token: 클라이언트 ↔ HA REST API 인증용, HA 사용자 프로필에서 발급. 서로 다른 토큰이며 용도를 혼동하지 않는다.
- 제어는 클라우드를 경유한다. 클라이언트 → HA(service 호출) → ThinQ Cloud → 기기 순서로 전달되므로, 로컬 기기 제어 대비 지연이 있고 인터넷이 끊기면 제어도 끊긴다.
- 기기는 HA 안에서 엔티티(entity)로 나타난다. 예: 공기청정기 운전 모드 →
select.gonggiceongjeonggi_operating_mode(기기 이름의 로마자 표기 + 기능명으로 자동 생성).
| 항목 | 내용 |
|---|---|
| ThinQ 앱 기기 등록 | 제어할 가전이 LG ThinQ 모바일 앱에 등록·온라인 상태여야 한다 (HA가 기기를 직접 찾는 게 아니라 ThinQ 계정에 등록된 기기를 가져온다) |
| HA 버전 |
2024.11 이상 — 공식 LG ThinQ 통합(ThinQ Connect API 기반)이 이 버전부터 내장 |
| LG 계정 | ThinQ 앱에 로그인한 것과 같은 LG 계정으로 PAT를 발급해야 한다 |
- 브라우저에서 https://connect-pat.lgthinq.com 접속
- ThinQ 앱과 동일한 LG 계정으로 로그인
-
Add New Token → 토큰 이름 입력(예:
home-assistant) → 권한 범위 선택 후 생성 - 발급된 토큰 문자열을 복사해 둔다
- HA 웹 UI → 설정 → 기기 및 서비스 → 통합 추가
-
LG ThinQ검색 → 선택 - PAT 입력 + 국가 선택(대한민국) → 제출
- ThinQ 계정의 기기들이 자동으로 등록되고, 기기별 엔티티가 생성된다
개발자 도구 → 상태 화면에서 기기 이름으로 검색하면 생성된 엔티티 ID를 확인할 수 있다. 공기청정기 예:
| 엔티티 | 도메인 | 용도 |
|---|---|---|
select.gonggiceongjeonggi_operating_mode |
select |
운전 모드 (auto / dual_clean / circulator / clean) |
⚠️ 엔티티 ID는 ThinQ에 등록된 기기 이름의 로마자 표기로 자동 생성된다. 기기 이름을 바꾸거나 다른 환경에 재설치하면 ID가 달라질 수 있으므로, 클라이언트 코드에 하드코딩하지 말고 설정/환경값으로 관리한다.
REST API 호출에는 HA의 Long-Lived Access Token이 필요하다.
- HA 웹 UI 로그인 → 좌측 하단 프로필 → 보안 탭
- 맨 아래 장기 액세스 토큰 → 토큰 생성 (이름은 용도를 알 수 있게, 예:
tablet-fe-bff) - 생성 직후 한 번만 표시되므로 즉시 복사 → env 파일에 보관
# .env (커밋 금지)
HA_URL=http://<HA주소>:8123
HA_TOKEN=eyJhbGciOi...- 유효기간 10년, 폐기는 같은 화면에서 즉시 가능.
- 토큰 권한 = 발급 사용자 권한 (토큰 단위 read-only 스코프 없음). 조회·제어만 한다면 관리자 권한 없는 전용 사용자를 만들어 그 계정으로 발급하는 것을 권장한다.
모든 요청은 Authorization: Bearer <HA_TOKEN> 헤더를 붙인다. (ha-api.http #0~#3)
| # | 엔드포인트 | 용도 |
|---|---|---|
| 0 | GET /api/ |
연결·토큰 확인 ({"message": "API running."}) |
| 1 | GET /api/config |
HA 버전·설정 (헬스체크 겸용) |
| 2 | GET /api/states |
전체 엔티티 상태 목록 — 존재하는 entity_id 훑기 |
| 3 | GET /api/states/<entity_id> |
단일 엔티티 상태 (없으면 404) |
단일 엔티티 조회 예 — 공기청정기 운전 모드:
GET {{haUrl}}/api/states/select.gonggiceongjeonggi_operating_mode
Authorization: Bearer {{haToken}}{
"entity_id": "select.gonggiceongjeonggi_operating_mode",
"state": "auto",
"attributes": {
"options": ["auto", "dual_clean", "circulator", "clean"],
"friendly_name": "공기청정기 Operating mode"
},
"last_changed": "2026-08-02T04:10:22.513Z",
"last_updated": "2026-08-02T04:10:22.513Z"
}-
state는 항상 string이다 — 기기가 오프라인이면"unavailable", 초기화 전이면"unknown"이 올 수 있으므로 클라이언트는 이 값을 방어 처리한다. -
attributes.options가 제어(§4)에 넣을 수 있는 유효값 목록이다 — 제어 전에 이 조회로 확인한다. - REST 조회는 폴링 방식이다. 상태 변화를 실시간으로 받아야 하면 HA WebSocket API 또는 MQTT statestream을 별도 검토한다(이 문서 범위 밖).
HA에서 엔티티 제어는 상태를 직접 쓰는 게 아니라 도메인별 service 를 호출하는 방식이다:
POST /api/services/<도메인>/<서비스> body: { "entity_id": "...", ...파라미터 }
어떤 도메인에 어떤 서비스·파라미터가 있는지는 GET /api/services(#4)로 확인한다.
POST {{haUrl}}/api/services/select/select_option
Authorization: Bearer {{haToken}}
Content-Type: application/json
{
"entity_id": "select.gonggiceongjeonggi_operating_mode",
"option": "dual_clean"
}-
option은 §3 조회 응답의attributes.options에 있는 값만 유효하다. 목록에 없는 값을 보내면 400이 온다. - 공기청정기 운전 모드 유효값:
auto/dual_clean/circulator/clean.
on/off형 엔티티(switch·light·fan 등)는 도메인을 몰라도 homeassistant 도메인으로 제어할 수 있다:
POST {{haUrl}}/api/services/homeassistant/turn_off
Authorization: Bearer {{haToken}}
Content-Type: application/json
{ "entity_id": "switch.demo_plug" }turn_on / turn_off / toggle 셋 다 같은 형태다.
service 호출의 응답은 이 호출로 상태가 바뀐 엔티티 목록(배열) 이다. ThinQ처럼 클라우드를 경유하는 기기는 반영이 비동기라 빈 배열 []이 와도 실패가 아닐 수 있다 — 실제 변경 여부는 GET /api/states/<entity_id>(#3) 재조회로 확인한다.
⚠️ POST /api/states/<entity_id>는 HA 상태 머신의 값만 덮어쓸 뿐 실제 기기를 움직이지 않는다. 기기 제어에 쓰면 "HA 화면상으론 바뀌었는데 기기는 그대로"인 상태가 된다. 용도는sensor처럼 제어 service가 없는 엔티티에 테스트 데이터를 주입하는 것뿐이다 (존재하지 않는 entity_id면 새로 생성된다).
appStore/tablet-fe/ha-api.http에 위 요청들이 번호(#0~#8) 순으로 준비되어 있다.
-
VS Code REST Client 확장(
humao.rest-client) 설치 - env 연결 —
{{$dotenv VAR}}는.http파일과 같은 폴더의.env만 읽는다(경로 설정 없음)..env.local을 쓰는 레포에서는 심볼릭 링크로 연결한다:ln -s .env.local .env # .gitignore 의 .env* 규칙으로 커밋되지 않음 -
{{haUrl}}위에 마우스를 올려 값이 해석되는지 확인 → 각 요청 위 Send Request 클릭 - 권장 순서:
#0(연결 확인) →#2(entity_id 훑기) →#3(단일 조회,options확인) →#5/#6(모드 변경) →#3재조회(반영 확인)
| 증상 | 원인 · 조치 |
|---|---|
401 Unauthorized |
HA_TOKEN 누락/오타/폐기됨. #0으로 토큰부터 검증 |
404 Not Found |
entity_id 오타 또는 미생성. #2 전체 목록에서 실제 ID 확인 |
400 Bad Request (select) |
option 값이 attributes.options에 없음. #3으로 유효값 확인 |
제어 응답이 []
|
실패 아님(클라우드 경유 비동기 반영 가능) — #3 재조회로 판단 |
state: "unavailable" |
기기 오프라인 또는 ThinQ Cloud 연결 끊김. ThinQ 앱에서 기기 상태 확인 |
| 통합 자체가 인증 오류 | LG PAT 폐기/만료 — 설정 → 기기 및 서비스 → LG ThinQ에서 재인증(PAT 재발급) |
⚠️ HA_TOKEN·LG PAT는 절대 저장소에 커밋하지 않는다. env 파일(서버 env)에만 두고,.http파일에는{{$dotenv}}참조만 남긴다.
서버가 위 REST API를 대신 호출하고, 백오피스 LG 가전 관리(/lg-appliances)에서 가전별 테스트를 한다.
| 항목 | 내용 |
|---|---|
| 서버 env |
HA_URL(기본 http://home-assistant:8123, 같은 compose) · HA_TOKEN(HA Long-Lived Access Token — devops GitHub Secret/Variable BE_HA_TOKEN이 deploy 워크플로 env → compose로 주입, 또는 러너 ~/orchestration-server.env). 토큰은 서버에만 있고 브라우저로 내려가지 않는다 |
| 어드민 API |
GET /api/admin/ha/status(연결·버전) · GET /api/admin/ha/entities?q=&domain=(전체 엔티티 검색) · GET /api/admin/ha/entities/{entity_id} · POST /api/admin/ha/services/{domain}/{service} {entity_id, data} — 호출 후 0.7초 뒤 재조회한 after를 함께 돌려준다(§4.3 비동기 반영) |
| 가전 매핑 |
lg_appliances 테이블(093): 스타일러 / 공기청정기 / 냉장고 3행 고정. entities = 기능 키 → entity_id JSON. GET/PUT /api/admin/lg-appliances/{id}, GET …/{id}/states
|
| 백오피스 | 가전 카드마다 기능(스타일러: 행정 동작·코스·종료 예약·전원 / 공기청정기: 운전 모드·전원·풍량·미세먼지 / 냉장고: 냉장·냉동 온도·급속·문)에 엔티티를 지정하면 도메인에 맞는 컨트롤이 자동으로 뜬다 — select→options 버튼, number→값 입력(number.set_value), switch/fan/light→켜기·끄기·토글(homeassistant.*), climate→온도(climate.set_temperature)·모드, button→press, sensor→읽기 전용. 임의 서비스 호출·속성 보기도 가능 |
엔티티 ID는 §1.4대로 환경마다 다르므로 코드에 없고 백오피스에서 지정한다. HA에 LG ThinQ 통합(§1)이 먼저 추가돼 있어야 탐색기에 기기가 보인다. | 선택지 전원 제어 | 태스크/이벤트 선택지에
lg_appliance_id(lg-styler|lg-air-purifier|lg-refrigerator) +lg_power(on|off)를 두면(094), 태블릿이orchestration/{sessionId}/task/option/select·event/option/select로 그 선택지를 고를 때 서버가 해당 가전의entities.power엔티티에homeassistant.turn_on/turn_off를 호출한다. SPOT/반려로봇 명령과 독립이며 응답(…/select/response)에는 영향 없음.power엔티티가 미매핑이면 로그만 남기고 무시 | | 도착 자동화 |arrival_automation_actions.device_type = 'lg'(096),action = on \| off,params_json = {"appliance_id": "lg-…"}. 세션이 규칙의 장소에 도착하면 디바이스 큐(lg:{appliance_id}그룹)에서 앞 액션 완료 후 HAhomeassistant.turn_on/off를 호출하고, 호출 성공을 완료로 기록한다(ack 없음). 백오피스 자동화 에디터에서 디바이스 "LG 가전" 선택 |
- Google ADK 검토 (프레임워크·모델 비교)
- 페르소나 + 상황 카드 모델 (2차 시나리오 구동 방식)
- Mac Studio 로컬 LLM + Claude Opus 하이브리드 라우팅 전략
- 개발 일정·할 일 점검표 (단계별 진행 점검)
- 로봇 Adapter 개발 온보딩 (HA·MQTT 계정 등록, 토픽 적용, 테스트 송수신, 상태 확인)
- LG ThinQ 가전 연동 (HA 통합 · REST 데이터 취득 · 제어)
- 장소 도착 자동화 (태스크/이벤트/장소 규칙 → SPOT·로봇팔·반려로봇·Hub 자동 명령)
- 엔딩 화면 데이터 출처 점검 (차량 3필드 · 세션 종료 엔딩 5화면)