LocalThings 설치 가이드 (SmartThings API 유료화 대응)

대상: Home Assistant + SmartThings 연동 중이던 삼성 에어컨을 로컬 제어로 전환 참고 저장소: mbillow/localthings (HA 커스텀 컴포넌트), QuiteYellow/SmartThings-Local (저수준 프로토콜 라이브러리 겸 CA 인증서 발급 도구)

1. 개요

LocalThings는 SmartThings 클라우드를 거치지 않고 삼성 신형 가전(Tizen RT 3.x + DAWIT 3.0 이상 펌웨어)과 CoAP-over-DTLS로 LAN에서 직접 통신하는 정식 Home Assistant 커스텀 컴포넌트입니다.

설정 흐름(config flow) UI 지원 — YAML/env 편집 없이 설정 → 기기 및 서비스에서 바로 추가
기기 타입(에어컨, 건조기, 오븐, 식기세척기, 냉장고, 세탁기)을 자동 인식
상태 갱신은 가능하면 푸시(OBSERVE) 우선, 안 되면 폴링으로 자동 전환 (iot_class: local_push)
HA는 Samsung 클라우드를 전혀 거치지 않음 (단, 가전기기 자체는 여전히 삼성 클라우드로 자체 TLS 세션을 유지함 — 이건 기기 펌웨어 동작이라 통합이 막을 수 있는 부분이 아님)

지원 기기 타입

타입	레지스트리 파일
에어컨	`by_type/airconditioner.py`
건조기	`by_type/dryer.py`
오븐	`by_type/oven.py`
식기세척기	`by_type/dishwasher.py`
냉장고	`by_type/refrigerator.py`
세탁기	`by_type/washer.py`

2. Part 1 — 기기 호환성 확인

nmap -Pn -sU -p 49152-49160 <에어컨IP>

49152~49160 중 하나라도 open|filtered로 응답 → 신형 펌웨어일 가능성. 정확한 포트를 몰라도 됨 — config flow가 이 범위 전체를 자동으로 스윕해서 실제 응답하는 포트를 찾아줌.
8888/tcp만 열려있음 → 구형 펌웨어(2018~2022년경), 미지원.

UDP 스캔 특성상 open|filtered는 “응답이 없었다”는 뜻이라 100% 확정은 아님. 최종 확인은 실제 config flow 등록 시도로 이루어짐.

3. Part 2 — CA 인증서/키 확보 (최초 1회만)

LocalThings 저장소 자체에는 CA 번들이 없고, 별도 프로토콜 저장소의 스크립트로 발급받아야 합니다.

git clone https://github.com/QuiteYellow/SmartThings-Local.git st-local-protocol
cd st-local-protocol
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-bootstrap.txt
python setup_cert.py

실행 결과로 생성되는 파일들

파일	역할	HA에 입력?
`certs/.bundle/ac14k_m.pem` `certs/.bundle/ac14k_m.key`	AC14K_M 서명 CA 자체 — 삼성 기기가 공장 출하 시부터 신뢰하는 중간 CA	✅ 이걸 사용
`certs/client.pem` / `client.key` / `client_fullchain.pem`	스크립트가 이미 자체 발급까지 끝낸 최종 리프 인증서 (구버전 Docker+MQTT 브릿지 방식용)	❌ 불필요

왜 CA만 필요한가: HA 통합은 기기를 등록할 때마다 저장된 CA로 직접 리프 인증서를 발급하도록 설계되어 있습니다. 원본 기기의 인증서/키가 필요한 게 아니라, AC14K_M이 서명한 무언가만 있으면 되고 그 서명 작업 자체를 HA가 수행합니다.

왜 이게 작동하는가 (배경)

모든 삼성 Tizen/RT-OCF 가전의 공장 출하 ACL이 특정 UUID에 대해 perm=31(전체 CRUDN) 권한을 부여
AC14K_M은 오래전부터 공개되어 있고 2026년 현재도 기기 신뢰 저장소에 남아있는 중간 CA
원본 키홀더의 개인키가 없어도, 새로 키를 만들고 AC14K_M으로 서명받으면 동일한 신원으로 인증됨

CA 파일 내용 확인:

cat certs/.bundle/ac14k_m.pem
cat certs/.bundle/ac14k_m.key

-----BEGIN...-----부터 -----END...-----까지 전체를 복사해 둡니다.

4. Part 3 — HA에 LocalThings 통합 설치

설치

cp -r ~/localthings-repo/custom_components/localthings /path/to/homeassistant/config/custom_components/

또는 HACS에 mbillow/localthings를 custom repository(Integration 카테고리)로 추가 후 설치.

설치 후 HA 재시작.

기기 추가

설정 → 기기 및 서비스 → 통합 추가 → LocalThings
첫 기기: 에어컨 IP + Part 2에서 얻은 ac14k_m.pem / ac14k_m.key 내용을 각각 CA Certificate / CA Private Key 필드에 붙여넣기
제출 시 config flow가 자동으로 수행하는 작업:
- Samsung 클라우드 게이트웨이에서 현재 UUID 조회
- 저장된 CA로 이 기기 전용 리프 인증서 발급
- 49152~49160 포트 범위 스윕하여 살아있는 DTLS 포트 탐색
- /device/0 응답 확인 후 기기 타입 자동 감지
두 번째 기기부터는 IP만 입력 — 저장된 CA를 재사용해 자동으로 리프 인증서 발급

성공하면 기기 타입이 airconditioner로 인식되고 관련 엔티티들이 자동 생성됩니다. 엔티티는 기기 시리얼 기준으로 키가 잡히므로 이름은 자유롭게 변경 가능.

5. 알아두어야 할 특이사항

동시 세션 1개 제한: 삼성 RT-OCF DTLS는 기기당 활성 세션을 하나만 허용. 다른 클라이언트(예: 로컬 테스트 스크립트)를 동시에 켜두면 충돌함.
DTLS 세션이 가끔 끊김: 정상적인 기기 동작이며, 통합이 자동 재연결함. HA에서는 재연결 중 잠깟 마지막 값을 유지하는 정도로 보임(즉시 unavailable로 안 뜸). 재연결이 분당 여러 번 반복되면 실제 문제(Wi-Fi 링크, 경쟁 클라이언트)를 점검해야 함.
기기 타입 미인식 또는 지원 안 되는 리소스 노출 시: HA의 *설정 → 시스템 → 오류 수정(Repairs)*에 항목이 뜨고, 해당 기기의 진단 다운로드(계정/식별정보 이미 마스킹됨)를 이슈로 첨부하면 지원 확대에 도움이 됨.

6. 문제 발생 시 확인할 것

config flow 등록 단계에서 타임아웃/인증 실패가 나면 HA 로그(custom_components.localthings를 debug 레벨로) 확인
CA 파일을 잘못 넣었는지(리프 인증서 client.pem을 넣지 않았는지) 재확인
포트 스윕이 실패하면 에어컨이 실제로 신형 펌웨어인지(Part 1) 재검증

WordPress

LocalThings 설치