TrendShift 딥다이브 · 2026-07-13 · Daily #12

home-assistant/core 딥다이브
— 집 안의 모든 기기를 하나로 묶는 파이썬 홈 자동화 엔진

Home Assistant Core전구·센서·도어락·에어컨·CCTV 등 서로 다른 회사의 스마트홈 기기 수천 종을, 클라우드를 거치지 않고 "내 집 안에서" 하나로 묶어 자동화하는 오픈소스 소프트웨어다. 흔히 말하는 "Home Assistant"의 두뇌(백엔드)가 바로 이 저장소다. 기술적으로는 단일 이벤트 루프(asyncio) 위에서 도는 얇은 파이썬 프레임워크에, 1,474개의 "통합(integration)" 플러그인이 꽂히는 구조다. 코어는 8만 줄, 그 위에 붙는 통합은 137만 줄 — 즉 "거의 모든 기능이 플러그인"인 극단적 확장형 설계다. (저장소: home-assistant/core · Apache-2.0 · Python 3.14+ · CalVer 월간 릴리스(현재 2026.7 계열) · 최신 커밋 2026-07-13 · TrendShift 오늘 Daily #12)
목차
  1. 프로젝트 한 줄 요약
  2. 왜 지금 주목받는가
  3. 기술 스택 전체 지도
  4. 아키텍처 심화 분석
  5. 디렉토리 구조 해부
  6. 학습 포인트
  7. 하드웨어 / 시스템 요구사항
  8. 직접 해볼 수 있는 실습 과제
  9. 관련 기술 심화 학습 로드맵
  10. 핵심 키워드 사전
  11. 참고 링크

1프로젝트 한 줄 요약

이름부터 뜯어보기 — "Core"는 Home Assistant의 파이썬 심장(백엔드). 우리가 흔히 "홈어시스턴트"라 부르는 것의 알맹이

Home Assistant Core"집 안 스마트 기기들의 통역사이자 지휘자" 역할을 하는 파이썬 프로그램이다. 삼성 에어컨, 필립스 휴 전구, 샤오미 센서, 애플 홈킷 도어락… 이들은 서로 통신 규격이 완전히 다르지만, Home Assistant는 각 기기를 "상태(state)를 가진 엔티티(entity)"라는 하나의 공통 언어로 번역해, 한 화면에서 보고·제어하고 자동화 규칙("해가 지면 거실 불 켜기")을 걸 수 있게 한다.

중요한 구분: 이 저장소는 Home Assistant의 "Core(코어)", 즉 자동화 두뇌인 파이썬 백엔드만 담고 있다. 사용자가 보는 예쁜 대시보드(프론트엔드), 애드온을 관리하는 Supervisor, 라즈베리파이에 굽는 전용 OS(HAOS)는 전부 다른 저장소다(§4·§7에서 정리). 즉 "Home Assistant를 설치했다"는 말은 실제로는 이 Core를 중심에 두고 주변 조각을 조립한 결과다.

한 문장 비유

"국적이 제각각인 외교관 수천 명이 모인 국제회의장의, 만능 동시통역 시스템 + 의장(議長)"

스마트홈 기기들은 각자 다른 나라 말(Zigbee, Wi-Fi, Z-Wave, 클라우드 API…)을 쓰는 외교관 같다. 그냥 두면 서로 한마디도 못 알아듣는다.

Home Assistant Core는 이 회의장의 동시통역 시스템이다. 각 외교관(기기)에게 통역사(통합·integration)를 한 명씩 붙여, 모든 발언을 "엔티티의 상태 변화"라는 공용어로 바꿔 중앙 게시판(StateMachine)에 띄운다. 그리고 의장(자동화 엔진)이 "A가 이러면 B에게 저걸 시켜라"라는 안건을 진행한다. 새 나라(새 기기 회사)가 참가해도, 통역사 한 명(통합 하나)만 새로 채용하면 회의는 그대로 굴러간다.

핵심 용어
통합 (Integration)
Home Assistant가 특정 기기·서비스와 대화하는 방법을 담은 플러그인. 필립스 휴, 구글 캘린더, 날씨 API… 하나하나가 전부 통합이다. 현재 1,474개가 기본 탑재돼 있고, 각 통합은 manifest.json(명세서)과 파이썬 코드로 이뤄진다. Home Assistant의 방대함은 곧 "통합의 수"다.
핵심 용어
엔티티 (Entity) / 상태 (State)
Home Assistant가 다루는 가장 작은 단위. "거실 전구", "현관 온도센서" 같은 개별 대상 하나가 엔티티이고, 각 엔티티는 on/off·23.5°C 같은 상태(state) 하나와 여러 속성(attributes)을 갖는다. 세상의 온갖 기기가 이 단순한 "상태를 가진 물건"으로 통일되기 때문에 자동화가 가능해진다.

2왜 지금 주목받는가

TrendShift Daily #12 · "클라우드·구독 없이 내 데이터는 내 집에" — 프라이버시·로컬 우선이라는 시대정신

Home Assistant는 새 프로젝트가 아니라 2013년부터 이어져 온 스마트홈계의 리눅스 같은 존재다. 그런 오래된 대형 저장소가 트렌딩에 다시 오른다는 건, 코드보다 시대 흐름이 이 프로젝트로 사람들을 끌어당기고 있다는 신호다. (TrendShift의 굵은 숫자는 별 수가 아니라 사회적 언급 모멘텀이다.)

주목 포인트 1 — "로컬 우선(local-first)"이 무기가 된 시대

스마트홈 기기 회사들이 서버를 닫으면 멀쩡한 기기가 벽돌이 되는 사건이 반복되면서, "내 집 데이터가 왜 남의 클라우드를 거쳐야 하나"라는 불신이 커졌다. Home Assistant의 슬로건이 정확히 이 지점이다 — "local control and privacy first(로컬 제어와 프라이버시 우선)". 인터넷이 끊겨도, 회사가 망해도, 내 집 자동화는 내 집 안에서 계속 돈다.

주목 포인트 2 — Matter · 스마트홈 표준 전쟁의 중립 허브

Matter/Thread 같은 업계 공통 표준이 퍼지면서 "어느 회사 앱을 쓰지?"라는 고민이 커졌는데, Home Assistant는 특정 회사에 묶이지 않은 중립 허브다. 애플·구글·아마존·삼성 기기를 한 지붕 아래 섞어 쓰고 싶은 사용자에게 사실상 유일한 통합 해법이라, 표준 전쟁이 격해질수록 오히려 수요가 는다.

주목 포인트 3 — 압도적 생태계 규모 = 진입장벽이자 해자(moat)

기본 탑재 통합만 1,474개, 통합 코드가 137만 줄이다. "내가 가진 그 기기, 되나요?"에 대한 답이 거의 항상 "예"인 것. 신생 경쟁자가 이 목록을 따라잡는 건 사실상 불가능하다. 활발한 커뮤니티(HACS 커스텀 통합, 포럼, 블루프린트)까지 더하면, 규모 자체가 강력한 방어막이다.

주목 포인트 4 — AI·음성 어시스턴트의 로컬 대안

최근 코어에 helpers/llm.py·intent.py 같은 어시스턴트 파이프라인이 자리 잡으면서, "클라우드로 안 새는 로컬 음성비서"를 직접 굴리려는 흐름의 중심에 섰다. 빅테크 스피커의 사생활 우려에 대한 대안으로, 개발자·프라이버시 관심층에게 다시 주목받는 이유다.

3기술 스택 전체 지도

"비동기 파이썬 코어 + 별도 프론트엔드 + 격리 설치되는 통합 의존성" — 세 덩어리로 나눠 보기

Home Assistant의 스택을 이해하는 열쇠는 "코어는 얇고, 실제 기능은 전부 통합(플러그인)에 있다"는 점이다. 그래서 스택도 (1) 코어가 딛고 선 파이썬 기반 기술, (2) 눈에 보이는 프론트엔드, (3) 통합·인프라의 세 계층으로 나눠 보면 깔끔하다.

계층 1 — 백엔드 코어 (비동기 파이썬)

기술버전 · 역할
Python3.14.2 이상 필수(requires-python). 코어 전체가 asyncio 단일 이벤트 루프 위에서 도는 비동기 우선 설계.
aiohttp3.14.1. 웹 서버(REST·WebSocket API)이자 기기 통신용 HTTP 클라이언트. 코어 네트워킹의 뼈대.
voluptuous0.15.2. 설정(config) 검증 라이브러리. Pydantic이 아니라 이걸 쓴다 — cv.string 같은 검증기 모음(helpers/config_validation.py, 2,167줄)으로 사용자 YAML을 안전하게 파싱.
SQLAlchemy2.0.51. recorder 통합이 상태·이벤트 이력을 DB에 기록할 때 쓰는 ORM.
Jinja23.1.6. 자동화·템플릿 센서에서 {{ states('sensor.temp') }} 같은 템플릿을 평가하는 엔진.
orjson · ciso8601 · propcache · fnv-hash-fast전부 C 확장 가속기. 상태 변경이 초당 수천 번 일어나는 핫패스를 빠르게 만드는 최적화 의존성.
zeroconf · bluetooth · dhcpzeroconf 0.150.0 등. 네트워크에 새로 붙은 기기를 자동 발견(discovery)하는 스캐너들.
cryptography · bcrypt · PyJWT인증·토큰·암호화. 로그인 세션과 저장 데이터 보호.
astral · cronsimastral 2.2는 일출/일몰 계산(태양 기반 자동화), cronsim은 cron 스케줄 해석.
uv0.11.26. 통합별 pip 요구사항을 런타임에 격리 설치하는 초고속 패키지 매니저(아래 계층 3 참고).

포인트: 의존성 버전이 전부 ==못박혀(pinned) 있다. 수천 개 통합이 얽힌 거대 시스템에서 "어제 되던 게 오늘 안 됨"을 막으려는 재현성 우선 원칙이다.

계층 2 — 프론트엔드 (별도 저장소, 의존성으로 주입)

사용자가 보는 대시보드는 이 저장소에 소스가 없다. 별도 저장소 home-assistant/frontend에서 Lit + TypeScript로 만든 SPA를, 빌드된 파이썬 패키지 형태로 당겨 쓴다.

home-assistant-frontend20260624.5. frontend 통합의 manifest.json이 이 패키지를 requirements로 선언 → pip이 설치. 즉 백엔드는 "빌드 완성본"만 소비한다.
Lit (Web Components)React가 아니라 웹 표준 Lit 기반 커스텀 엘리먼트. 대시보드의 카드가 전부 웹 컴포넌트다.
WebSocket API프론트엔드↔코어는 주로 aiohttp 위의 WebSocket으로 실시간 통신(상태가 바뀌면 즉시 화면 갱신).

계층 3 — 통합 · 인프라 (플러그인과 배포)

manifest.json 기반 통합통합 하나 = manifest.json(명세) + 파이썬 모듈. 코어는 이 명세를 읽어 의존성·요구 라이브러리·디스커버리 규칙을 파악.
uv로 요구사항 격리 설치2,000개 라이브러리를 코어 배포에 다 넣지 않는다. 사용자가 실제로 켠 통합의 pip 패키지만 런타임에 uv로 설치(requirements.py).
Docker · HAOS배포는 컨테이너 이미지 또는 라즈베리파이용 전용 리눅스(HAOS). 설치 방식이 4가지로 갈리는 이유(§7).
recorder DB기본 SQLite 파일, 규모가 크면 MySQL/MariaDB·PostgreSQL로 교체 가능.
비유 — 스마트폰 OS와 앱스토어

코어(8만 줄)는 스마트폰 OS, 통합 1,474개(137만 줄)는 앱스토어의 앱들이라고 보면 된다. OS는 "앱이 지켜야 할 규칙과 공용 기능(화면·알림·저장)"만 제공하고, 실제로 뭔가를 하는 건 앱이다. 그래서 코어를 공부한다는 건 "안드로이드 앱 하나"가 아니라 "안드로이드 프레임워크 그 자체"를 뜯어보는 일에 가깝다.

4아키텍처 심화 분석

단일 이벤트 루프 + 4대 코어 객체 + "엔티티→플랫폼→통합→설정항목" 4계층

Home Assistant의 심장은 homeassistant/core.py(3,011줄) 안의 HomeAssistant 클래스다. 이 객체 하나가 시작될 때 네 개의 코어 부품을 조립하고, 이후 모든 일은 이 넷 사이의 대화로 이뤄진다.

┌─────────────────── HomeAssistant (core.py) ───────────────────┐ │ 단 하나의 asyncio 이벤트 루프 위에서 동작 │ │ │ │ ① bus EventBus "무슨 일이 일어났다"를 방송/구독 │ │ ② states StateMachine 모든 엔티티의 현재 상태 게시판 │ │ ③ services ServiceRegistry "이걸 해줘"라고 부를 수 있는 명령 │ │ ④ config Config 위치·단위·시간대 등 전역 설정 │ └───────────────┬────────────────────────────┬───────────────────┘ │ 상태가 바뀌면 │ 서비스 호출 EVENT_STATE_CHANGED 이벤트 발행 │ (예: light.turn_on) │ ▼ ┌───────────────▼──────────────┐ ┌──────────────────────────┐ │ 자동화/스크립트 엔진 │ │ 통합(Integration) 코드 │ │ "트리거→조건→액션" │──▶│ 실제 기기에 명령 전달 │ │ (helpers/script.py 등) │ │ (aiohttp/블루투스/...) │ └──────────────────────────────┘ └──────────────────────────┘

4-1. 네 개의 코어 객체 (core.py)

HomeAssistant.__init__이 만드는 핵심 4형제다.

객체정체 · 핵심 메서드
EventBus
(L1506)
발행/구독(pub-sub) 방송국. async_listen("event_type", cb)로 구독하고 async_fire(...)로 방송. 상태가 바뀌면 EVENT_STATE_CHANGED가 여기로 흐른다. 시스템의 모든 소통이 이 버스를 지난다.
StateMachine
(L2200)
모든 엔티티의 현재 상태 게시판. async_set(entity_id, state)로 상태를 갱신하면 자동으로 이벤트를 발행. 읽기 속도를 위해 내부 _states_data 딕셔너리를 직접 만진다.
ServiceRegistry
(L2620)
부를 수 있는 명령 목록. light.turn_on, climate.set_temperature 같은 서비스를 async_register로 등록하고 async_call로 실행. 구조는 dict[도메인][서비스].
Config집 위치(위경도)·단위계·시간대·언어 등 전역 설정. 일출 자동화, 단위 변환 등이 여기에 의존.
핵심 개념 — 왜 "비동기(async)"가 전부인가
단일 이벤트 루프 + @callback + executor 탈출구
Home Assistant는 스레드를 잔뜩 띄우는 대신, 하나의 이벤트 루프에서 수천 개의 코루틴을 번갈아 돌린다. 그래서 "느린 작업이 루프를 막으면" 집 전체가 멈춘다. 이를 막는 장치가 셋이다 — (1) @callback 데코레이터(core.py L211): "이 함수는 절대 안 막힌다"는 표식, (2) block_async_io.py: open()·time.sleep()·import 같은 블로킹 호출을 몰래 감시해 "어느 통합이 루프를 막는지" 경고, (3) async_add_executor_job(...)(L871): 진짜로 막히는 작업(파일·구형 라이브러리)은 별도 스레드풀로 던지는 탈출구.

4-2. "엔티티 → 플랫폼 → 통합 → 설정항목" 4계층

기기 하나가 화면에 뜨기까지의 조립 순서다. 아래에서 위로 읽으면 "물리 기기 → 사용자 설정"이 된다.

┌────────────────────────────────────────────────────────────┐ │ ConfigEntry "거실 Hue 브릿지" — UI로 추가한 설정 1건 │ ← config_entries.py ├────────────────────────────────────────────────────────────┤ │ Integration "hue" 통합 — 브릿지와 대화하는 코드+manifest │ ← components/hue/ ├────────────────────────────────────────────────────────────┤ │ Platform "hue의 light 플랫폼" — 전구들을 light 도메인에 │ ← entity_platform.py │ 등록 (async_add_entities([...])) │ ├────────────────────────────────────────────────────────────┤ │ Entity "거실 전구", "주방 전구" … 개별 대상 + 상태 │ ← helpers/entity.py └────────────────────────────────────────────────────────────┘ 엔티티 45개 도메인: light, sensor, switch, climate, cover, fan, ...
Entity
(entity.py, 1,786줄)
가장 작은 단위. 개발자는 state·available·unique_id 같은 프로퍼티를 오버라이드하고, async_added_to_hass()(등록됨)·async_update_ha_state()(상태 밀어넣기) 훅으로 생명주기를 다룬다.
Platform
(entity_platform.py, 1,308줄)
"이 통합이 light 도메인에 내놓을 엔티티들"의 등록 창구. async_add_entities([...])로 엔티티를 코어에 밀어넣는다.
Integration기기·서비스 한 종류와 대화하는 코드 묶음. manifest.json이 정체성.
ConfigEntry
(config_entries.py, 4,212줄)
사용자가 UI에서 "추가"를 눌러 만든 설정 인스턴스 1건. 상태 머신(8개 상태)으로 로딩/재시도/언로드를 관리.

4-3. 부팅 시퀀스 (bootstrap.py, 1,112줄)

수천 개 통합을 한꺼번에 켜면 느리고 위험하다. 그래서 단계(stage)별로 나눠, 각 단계 안에서는 병렬로 켠다.

Stage 0 로깅·HTTP → frontend → recorder(DB) → zeroconf(mDNS) [기반 필수] │ Stage 1 디스커버리(bluetooth·dhcp·ssdp·usb) + cloud + hassio [타임아웃 120초] │ Stage 2 나머지 모든 통합 [타임아웃 300초] │ Wrap-up async_block_till_done — 잔여 작업이 끝날 때까지 대기 [300초]

흥미로운 점: 타임아웃을 넘겨도 죽지 않고 "그냥 진행(moving forward)" 로그를 남기고 넘어간다(우아한 실패). 단 하나 frontendCRITICAL_INTEGRATIONS로 지정돼, 이게 실패하면 최소 구성으로 부팅하는 복구 모드(recovery mode)로 들어간다 — "화면이라도 떠야 사용자가 고칠 수 있다"는 판단이다.

4-4. 핵심 설계 패턴 — DataUpdateCoordinator (update_coordinator.py, 711줄)

Home Assistant를 공부할 때 가장 자주 인용되는 모범 패턴이다. 문제 상황: 클라우드 날씨 API에서 "현재 온도·습도·풍속" 3개 센서를 만들 때, 각 센서가 따로 API를 부르면 호출이 3배가 되고 요금·속도 제한에 걸린다.

[나쁨] 온도센서 ─▶ API 호출 습도센서 ─▶ API 호출 한 번에 쓸 데 3번 호출 (N+1 문제) 풍속센서 ─▶ API 호출 [좋음] ┌── 온도센서 Coordinator ──┼── 습도센서 API 1번 → 셋이 결과를 공유(구독) (1회 fetch) └── 풍속센서

DataUpdateCoordinator는 "데이터를 한 번만 가져와 여러 엔티티가 구독해 나눠 쓰게" 한다. 서브클래스가 _async_update_data()만 구현하면 되고, 실패 시 UpdateFailed를 던지면 모든 구독 엔티티가 자동으로 unavailable이 된다. 게다가 수천 개 통합이 정각에 동시에 폴링해 서버가 출렁이는 것을 막으려고, 각 코디네이터의 갱신 시점을 마이크로초 단위로 랜덤하게 흩뿌리고(random stagger) Debouncer로 연타를 흡수한다. 대규모 설치에서 진짜 효과가 나는 설계다.

5디렉토리 구조 해부

코어는 homeassistant/ 하나. 그 안에서 "최상위 파일 16개 + helpers/ 70여 개"가 전부의 뼈대

거대해 보이지만, 실제 프레임워크의 뼈대는 homeassistant/ 최상위 파일 몇 개와 helpers/에 압축돼 있다. components/(1,474개 통합)는 "앱들"이라 지금은 건너뛰고, 프레임워크 코드만 본다.

homeassistant/ ├── core.py ★ 심장부: HomeAssistant / EventBus / StateMachine / ServiceRegistry ├── core_config.py Config 객체(위치·단위·시간대) ├── bootstrap.py ★ 부팅 시퀀스(스테이지 0/1/2) ├── config_entries.py ★ UI 설정 인스턴스 + ConfigFlow(설정 마법사) ├── data_entry_flow.py 다단계 플로우(마법사) 엔진 ├── setup.py ★ async_setup_component — 통합+의존성 켜기 ├── loader.py 통합 로더 + manifest.json 파싱(~1,800줄) ├── requirements.py 통합별 pip 요구사항을 uv로 설치 ├── const.py 상수 + 버전(MAJOR/MINOR/PATCH) + Platform 45종 ├── config.py configuration.yaml 로딩/검증 ├── exceptions.py HomeAssistantError 등 예외 계층 ├── runner.py 이벤트 루프 실행 + 시그널 처리 ├── __main__.py CLI 진입점 (hass 명령) ├── block_async_io.py 블로킹 호출 감시견(런타임 몽키패치) ├── backup_restore.py 백업/복원 │ ├── components/ ← 1,474개 통합("앱들"). 코어 아님 ├── helpers/ ← 통합이 공통으로 쓰는 유틸(아래) ├── util/ 저수준 유틸(시간·색·네트워크 dt/color/...) ├── auth/ 인증·권한(로그인, 토큰, 권한 정책) ├── generated/ 자동 생성 조회표(zeroconf/dhcp/ssdp 매칭) ├── scripts/ CLI 보조 스크립트 └── brands/ 통합 브랜드 메타데이터

helpers/ — 통합 개발자가 매일 쓰는 도구상자

파일역할
entity.py
entity_platform.py
entity_component.py
§4-2의 엔티티/플랫폼/컴포넌트 3형제. 통합이 엔티티를 만드는 기본 뼈대.
update_coordinator.py§4-4의 DataUpdateCoordinator 패턴. 폴링형 통합의 표준.
config_validation.py2,167줄. cv.string·cv.positive_intvoluptuous 검증기 모음. 사용자 설정을 안전하게 파싱하는 무기고.
event.py1,964줄. async_track_state_change·async_track_time_interval"~하면 알려줘"류 추적 헬퍼. 자동화 트리거의 토대.
entity_registry.py
device_registry.py
area_registry.py
floor/label/category
엔티티·기기·구역·층·라벨을 영속 저장하는 레지스트리들. "이 전구는 2층 거실에 있다" 같은 조직 정보.
script.py · condition.py · trigger.py자동화의 3요소 — 트리거→조건→액션 시퀀스를 실행하는 엔진.
storage.py631줄. Store = JSON 영속 헬퍼. 설정을 .storage/ 폴더에 안전하게 저장.
aiohttp_client.py통합들이 공유하는 HTTP 세션(커넥션 재사용).
intent.py · llm.py음성·LLM 어시스턴트 파이프라인(로컬 음성비서의 토대).
핵심 용어
generated/ 디렉토리 — 자동 생성 조회표
사람이 손으로 안 쓰고 스크립트가 만들어내는 파일들. 예: 네트워크에 _hue._tcp.local.라는 zeroconf 신호가 뜨면 "아, Hue 통합을 켤 후보다"라고 즉시 매칭할 수 있게, 모든 통합의 manifest.json 디스커버리 규칙을 미리 한 표로 모아둔 것. 덕분에 기기를 꽂으면 자동으로 "새 기기 발견" 알림이 뜬다.

6학습 포인트

이 저장소에서 진짜로 배울 것 — "대규모 비동기 파이썬 + 플러그인 프레임워크"를 어떻게 설계하나

Home Assistant Core는 단순한 앱이 아니라 "10년 넘게 유지된 초대형 파이썬 프레임워크"다. 배울 거리를 기술별로 정리한다.

배울 것 1 — asyncio를 "제품 규모"로 쓰는 법

튜토리얼의 async def를 넘어, 실전에서 이벤트 루프를 어떻게 지키는가를 배운다. @callback 표식, executor로 블로킹 오프로드, block_async_io.py의 런타임 감시, 태스크를 _tasks/_background_tasks 버킷으로 추적해 안전 종료 — 전부 "수천 개의 서드파티 코드가 하나의 루프를 공유할 때 생기는 문제"를 다루는 실전 기법이다.

배울 것 2 — 플러그인 아키텍처의 교과서

"코어는 얇게, 기능은 플러그인으로"를 극단까지 밀어붙인 사례. 명세 파일(manifest.json) 기반 로딩, 의존성 그래프 해소(setup.py의 Future 기반 중복 방지), 통합별 요구사항 격리 설치(uv)까지 — 확장 가능한 시스템을 설계할 때 그대로 참고할 만한 패턴이 가득하다.

배울 것 3 — 설정 검증을 코드가 아니라 "스키마"로

사용자가 YAML로 온갖 설정을 쏟아내는 시스템에서, voluptuous 스키마로 입력을 선언적으로 검증하는 법을 배운다. Pydantic만 알던 사람에게 "또 다른 검증 철학"을 보여준다(helpers/config_validation.py).

배울 것 4 — DataUpdateCoordinator = 실전 캐싱/구독 패턴

§4-4의 코디네이터는 사실 "공유 캐시 + 관찰자(observer) + 디바운스 + 지터(jitter)"를 한 클래스에 녹인 것이다. API 요금·속도 제한이 있는 외부 서비스를 여러 소비자가 나눠 쓸 때 어디서든 쓸 수 있는 범용 설계다.

배울 것 5 — 대형 오픈소스의 "성능 각인"

코어 클래스마다 __slots__(메모리 절약), @cached_property + 수동 캐시 무효화, C 확장 의존성(orjson 등), backing dict 직접 접근 같은 미세 최적화가 노골적으로 박혀 있다. "언제 가독성을 희생해 성능을 택하는가"의 실제 판단 사례를 볼 수 있다.

실습 아이디어 (가볍게)
코어를 "라이브러리처럼" 20줄로 띄워보기

pip install homeassistant 후, 파이썬에서 HomeAssistant 객체를 직접 만들고 hass.states.async_set("demo.hello", "world")로 상태를 넣은 뒤 hass.bus.async_listen(...)로 이벤트를 받아보면, §4의 4대 객체가 교과서가 아니라 실제로 손에 잡힌다.

7하드웨어 / 시스템 요구사항

"어디에 설치하느냐"가 곧 4가지 방식 — Core만 vs OS까지 통째로

Home Assistant의 최소 요구는 소박하지만, "설치 방식"에 따라 필요한 것이 크게 달라진다. 먼저 코어 자체의 최소 사양부터.

항목요구
Python3.14.2 이상(코어 venv 설치 시). 최신 파이썬을 빠르게 따라가는 편이라 구버전은 안 됨.
대표 하드웨어라즈베리파이 4/5, 미니 PC, NAS, 가상머신 등. RPi에서 무리 없이 도는 가벼움이 강점.
메모리2GB부터 실사용 가능(통합을 많이 켤수록 증가). 대규모(수백 기기)면 4GB+ 권장.
저장소32GB+ SD/SSD. 이력 DB(recorder)가 쌓이므로 SD카드보다 SSD 권장.
데이터베이스기본 SQLite(파일 자동 생성). 대규모면 MariaDB/MySQL 8.0+ 또는 PostgreSQL로 교체. SQLite는 3.40.1+.

설치 방식 4가지 — 무엇이 다른가

"Home Assistant를 깐다"는 말이 사람마다 다른 걸 뜻하는 이유. Core(이 저장소)를 어디까지 감싸느냐의 차이다.

방식구성 · 특징
HAOS
(Operating System)
가장 권장. 전용 리눅스 이미지를 RPi/미니PC에 통째로 굽는다. Core + Supervisor + 애드온 스토어까지 다 포함. "가전제품처럼" 쓰는 방식.
Container
(Docker)
Core만 담긴 공식 Docker 이미지를 돌린다. Supervisor·애드온 없음. 이미 서버·NAS를 굴리는 사람에게 적합.
Supervised직접 만든 리눅스 위에 Supervisor까지 얹는 고급 방식. 유연하지만 관리 부담이 크다.
Core (venv)이 저장소를 파이썬 가상환경에 pip 설치. Supervisor·애드온 없이 순수 코어만. 개발·학습에 딱.
생태계 정리 — 헷갈리는 4개 저장소
Core vs Frontend vs Supervisor vs OS(HAOS)
Core(이 저장소) = 파이썬 자동화 엔진. Frontend(home-assistant/frontend) = Lit/TS 대시보드, 빌드본이 의존성으로 주입. Supervisor(home-assistant/supervisor) = 애드온·백업·업데이트를 관리하는 Docker 오케스트레이터(HAOS·Supervised에만). Operating System / HAOS(home-assistant/operating-system) = RPi에 굽는 최소 리눅스. 여기에 유료 Nabu Casa 클라우드(hass-nabucasa 클라이언트로 연결, 원격 접속·음성)까지 더하면 전체 그림이 완성된다.

8직접 해볼 수 있는 실습 과제

읽기만 하면 안 남는다 — 난이도별로 손을 움직여 코어를 체득하는 과제 5개
난이도 ★☆☆ · 입문

1. 코어 4대 객체를 직접 만져보기

pip install homeassistant 후, 20줄짜리 스크립트에서 HomeAssistant()를 만들고 hass.states.async_set("test.lamp", "on")로 상태를 넣어본다. 그다음 hass.bus.async_listen("state_changed", 콜백)을 걸고 상태를 off로 바꿔, EVENT_STATE_CHANGED가 실제로 흐르는지 콘솔로 확인한다. §4의 그림이 손에 잡힌다.

난이도 ★☆☆ · 입문

2. 나만의 최소 통합(integration) 만들기

config/custom_components/hello/ 폴더에 manifest.json(domain·name만)과 sensor.py 하나를 넣어, 항상 42를 반환하는 센서 엔티티 1개를 띄운다. Entity 상속 → state 프로퍼티 오버라이드 → async_add_entities([...])의 최소 3단계를 몸으로 익힌다.

난이도 ★★☆ · 중급

3. DataUpdateCoordinator로 공개 API 센서 만들기

무료 공개 API(예: 환율·날씨·코인 시세)를 DataUpdateCoordinator로 5분마다 1번만 호출하고, 거기서 여러 센서 엔티티(값·변화율 등)가 데이터를 나눠 쓰게 만든다. _async_update_data() 구현, UpdateFailed 처리, CoordinatorEntity 상속을 다뤄본다 — 실전 통합의 표준 골격이다.

난이도 ★★☆ · 중급

4. ConfigFlow로 "UI 설정 마법사" 붙이기

과제 3의 통합에 config_flow.py를 추가해, YAML 대신 UI에서 API 키를 입력받아 추가되게 한다. ConfigFlow 상속, async_step_user, voluptuous 스키마로 폼 정의를 경험한다. 요즘 통합의 60%(893개)가 이 방식이라는 걸 몸으로 이해하게 된다.

난이도 ★★★ · 심화

5. 이벤트 루프를 막아보고, 감시견에 걸려보기

통합 안에서 일부러 time.sleep(5)나 동기 requests.get()을 호출해 집 전체가 멈추는 것block_async_io.py의 경고 로그를 직접 목격한다. 그다음 await hass.async_add_executor_job(...)로 고쳐, "블로킹 → executor 오프로드"의 전후 차이를 체감한다. asyncio 실전 감각의 핵심.

9관련 기술 심화 학습 로드맵

"파이썬 중급자 → Home Assistant 통합 기여자"까지, 4주 코스
주차목표 · 학습 내용
1주차
asyncio 기초 체력
async/await, 이벤트 루프, asyncio.gather, 태스크·퓨처, "블로킹이 왜 위험한가"를 확실히. → 과제 1·5로 코어의 루프 감각 잡기.
2주차
엔티티·통합 모델
Entity/Platform/Integration/ConfigEntry 4계층과 manifest.json 스키마, IoT 클래스(local_push 등) 이해. → 과제 2로 최소 통합 완성.
3주차
데이터·설정 흐름
DataUpdateCoordinator 패턴, voluptuous 검증, ConfigFlow 마법사, 레지스트리(엔티티/기기/구역). → 과제 3·4로 "제대로 된 통합" 골격 습득.
4주차
자동화·기여
트리거→조건→액션(script.py/trigger.py), 이벤트 추적 헬퍼(event.py), recorder/DB, 품질 척도(quality_scale)와 기여 가이드(개발 컨테이너·테스트). → 실제 PR 도전.
학습 순서 팁

Home Assistant 통합 개발은 "프레임워크 규칙을 먼저 배우고 그 안을 채우는" 일이라, 무작정 코드를 읽기보다 공식 Developer Docs의 "Building an integration" 튜토리얼을 따라 손코딩하며, 막힐 때 이 문서의 §4·§5로 "왜 이렇게 하지?"를 확인하는 왕복 학습이 가장 빠르다.

10핵심 키워드 사전

이 문서에 나온 용어를 한 번에 — 통합 개발·문서를 읽을 때 계속 마주칠 단어들
용어
Integration (통합)특정 기기·서비스와 대화하는 플러그인. 코어에 1,474개 기본 탑재.
Entity (엔티티)상태를 가진 최소 단위(전구·센서 등). 45개 도메인(light·sensor·climate…)으로 분류.
State / StateMachine엔티티의 현재 값과, 그 값들을 모아 관리하는 코어 객체.
EventBus"무슨 일이 일어났다"를 발행/구독하는 코어의 방송국.
Servicelight.turn_on처럼 부를 수 있는 명령. ServiceRegistry에 등록.
ConfigEntry / ConfigFlowUI로 추가한 설정 인스턴스 1건 / 그걸 만드는 설정 마법사(다단계 폼).
manifest.json통합의 명세서 — domain·dependencies·requirements·iot_class·config_flow 등.
IoT Class통합의 통신 방식 4분류: local_push(로컬 즉시 통보·가장 빠름)·local_polling·cloud_push·cloud_polling. 여기에 calculated·assumed_state 추가.
DataUpdateCoordinatorAPI를 1번만 호출해 여러 엔티티가 데이터를 공유하게 하는 표준 패턴.
@callback"이 함수는 절대 블로킹하지 않아 이벤트 루프에서 즉시 실행해도 안전"이라는 표식.
executor job블로킹 작업을 별도 스레드풀로 던져 이벤트 루프를 지키는 탈출구.
Recorder상태·이벤트 이력을 DB(SQLite/MySQL/Postgres)에 기록하는 통합.
voluptuousHome Assistant가 쓰는 설정 검증 라이브러리(Pydantic 아님). cv.string 등.
Supervisor / HAOS애드온·백업 관리자 / RPi에 굽는 전용 리눅스. Core와 별개 저장소.
CalVerHome Assistant의 버전 체계 YYYY.M.PATCH(예 2026.7). 매달 릴리스.

11참고 링크

공식 소스부터 통합 개발 문서까지
구분링크
GitHub (Core)github.com/home-assistant/core — 이 저장소(백엔드)
공식 사이트home-assistant.io — 설치·사용자 문서
Developer Docsdevelopers.home-assistant.io — 통합 개발 튜토리얼·아키텍처(필독)
Frontendgithub.com/home-assistant/frontend — Lit/TS 대시보드
Supervisorgithub.com/home-assistant/supervisor — 애드온 오케스트레이터
Operating Systemgithub.com/home-assistant/operating-system — HAOS 이미지
커뮤니티community.home-assistant.io(포럼) · HACS(커스텀 통합 스토어)