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 (기기 이름의 로마자 표기 + 기능명으로 자동 생성).

1. 브라우저에서 https://connect-pat.lgthinq.com 접속
2. ThinQ 앱과 동일한 LG 계정으로 로그인
3. Add New Token → 토큰 이름 입력(예: home-assistant) → 권한 범위 선택 후 생성
4. 발급된 토큰 문자열을 복사해 둔다

1. HA 웹 UI → 설정 → 기기 및 서비스 → 통합 추가
2. LG ThinQ 검색 → 선택
3. PAT 입력 + 국가 선택(대한민국) → 제출
4. ThinQ 계정의 기기들이 자동으로 등록되고, 기기별 엔티티가 생성된다

개발자 도구 → 상태 화면에서 기기 이름으로 검색하면 생성된 엔티티 ID를 확인할 수 있다. 공기청정기 예:

⚠️ 엔티티 ID는 ThinQ에 등록된 기기 이름의 로마자 표기로 자동 생성된다. 기기 이름을 바꾸거나 다른 환경에 재설치하면 ID가 달라질 수 있으므로, 클라이언트 코드에 하드코딩하지 말고 설정/환경값으로 관리한다.

REST API 호출에는 HA의 Long-Lived Access Token이 필요하다.

1. HA 웹 UI 로그인 → 좌측 하단 프로필 → 보안 탭
2. 맨 아래 장기 액세스 토큰 → 토큰 생성 (이름은 용도를 알 수 있게, 예: tablet-fe-bff)
3. 생성 직후 한 번만 표시되므로 즉시 복사 → env 파일에 보관

# .env (커밋 금지)
HA_URL=http://<HA주소>:8123
HA_TOKEN=eyJhbGciOi...

• 유효기간 10년, 폐기는 같은 화면에서 즉시 가능.
• 토큰 권한 = 발급 사용자 권한 (토큰 단위 read-only 스코프 없음). 조회·제어만 한다면 관리자 권한 없는 전용 사용자를 만들어 그 계정으로 발급하는 것을 권장한다.

모든 요청은 Authorization: Bearer <HA_TOKEN> 헤더를 붙인다. (ha-api.http #0~#3)

단일 엔티티 조회 예 — 공기청정기 운전 모드:

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) 순으로 준비되어 있다.

1. VS Code REST Client 확장(humao.rest-client) 설치
2. env 연결 — {{$dotenv VAR}}는 .http 파일과 같은 폴더의 .env만 읽는다(경로 설정 없음). .env.local을 쓰는 레포에서는 심볼릭 링크로 연결한다:

   ln -s .env.local .env   # .gitignore 의 .env* 규칙으로 커밋되지 않음

3. {{haUrl}} 위에 마우스를 올려 값이 해석되는지 확인 → 각 요청 위 Send Request 클릭
4. 권장 순서: #0(연결 확인) → #2(entity_id 훑기) → #3(단일 조회, options 확인) → #5/#6(모드 변경) → #3 재조회(반영 확인)

⚠️ HA_TOKEN·LG PAT는 절대 저장소에 커밋하지 않는다. env 파일(서버 env)에만 두고, .http 파일에는 {{$dotenv}} 참조만 남긴다.

서버가 위 REST API를 대신 호출하고, 백오피스 LG 가전 관리(/lg-appliances)에서 가전별 테스트를 한다.

엔티티 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} 그룹)에서 앞 액션 완료 후 HA homeassistant.turn_on/off를 호출하고, 호출 성공을 완료로 기록한다(ack 없음). 백오피스 자동화 에디터에서 디바이스 "LG 가전" 선택 |