커스텀 컴포넌트 개발 입문: 파이썬(Python)으로 나만의 HA 통합 구성요소(Integration) 만들기 (기초)

 

1. 커스텀 컴포넌트(Custom Component)란?

우리가 HACS(Home Assistant Community Store)에서 다운로드하는 모든 것들이 바로 '커스텀 컴포넌트'입니다. 전 세계의 능력자(개발자)들이 파이썬으로 코드를 짜서 공유한 것들이죠.

HA의 구조는 간단합니다.

1. /config/custom_components/ 폴더 안에,
2. 내_컴포넌트_이름/ 폴더를 만들고,
3. 그 안에 약속된 파일(manifest.json, __init__.py)을 넣으면,
4. HA가 부팅할 때 이를 읽어들여 실행합니다.

오늘은 거창한 API 연동 대신, HA가 시작될 때 "Hello World!"라는 알림을 띄우고, 나만의 서비스를 등록하는 가장 기초적인 컴포넌트를 만들어 봅니다.

2. [준비물] 개발 환경

• 필수: Home Assistant가 설치된 서버
• 필수: 파일 편집 도구 (VS Code 애드온 또는 Samba)
• 권장: 파이썬(Python) 기초 지식 (변수, 함수, 비동기 처리에 대한 이해)

3. [실습 1] 폴더 및 매니페스트(Manifest) 만들기

먼저 우리 컴포넌트의 '신분증'을 만듭니다.

1. HA의 /config 폴더(configuration.yaml이 있는 곳)로 이동합니다.
2. custom_components 폴더가 없다면 만듭니다.
3. 그 안에 **hello_world**라는 폴더를 만듭니다. (이것이 우리 컴포넌트의 도메인(Domain) 이름이 됩니다.)
4. hello_world 폴더 안에 manifest.json 파일을 만들고 아래 내용을 입력합니다.

JSON

 

{
  "domain": "hello_world",
  "name": "Hello World Integration",
  "codeowners": ["@your_github_id"],
  "config_flow": false,
  "documentation": "https://www.example.com",
  "iot_class": "local_push",
  "issue_tracker": "https://www.example.com/issues",
  "requirements": [],
  "version": "1.0.0"
}

• 설명: 이 파일은 HA에게 "나는 hello_world라는 1.0.0 버전의 로컬 컴포넌트야"라고 알려주는 역할을 합니다.

4. [실습 2] 파이썬 로직 작성 (__init__.py)

이제 실제 작동하는 코드를 작성합니다. hello_world 폴더 안에 __init__.py 파일을 만듭니다.

HA는 비동기(Async) 기반이므로 async와 await 키워드를 사용합니다.

Python

 

"""The Hello World integration."""
import logging
from homeassistant.core import HomeAssistant, ServiceCall

# 로깅 설정 (로그를 찍기 위해 필요)
_LOGGER = logging.getLogger(__name__)

# 컴포넌트의 도메인 이름
DOMAIN = "hello_world"

async def async_setup(hass: HomeAssistant, config: dict) -> bool:
    """초기 설정 함수: HA가 부팅될 때 이 함수가 실행됩니다."""
    
    _LOGGER.info("Hello World 컴포넌트가 시작되었습니다!")

    # 1. HA 영구 알림(Persistent Notification) 생성
    hass.components.persistent_notification.async_create(
        "안녕하세요! 커스텀 컴포넌트가 성공적으로 로드되었습니다.", 
        title="Hello World"
    )

    # 2. 나만의 서비스 등록 함수 정의
    async def handle_say_hello(call: ServiceCall):
        """서비스가 호출되었을 때 실행될 로직"""
        name = call.data.get("name", "친구") # 서비스 데이터에서 'name'을 가져옴
        
        _LOGGER.info(f"서비스 호출됨: {name}에게 인사합니다.")
        
        # 다시 알림을 띄워 응답
        hass.components.persistent_notification.async_create(
            f"반갑습니다, {name}님! 이것은 파이썬으로 만든 서비스입니다.",
            title="인사 서비스"
        )

    # 3. 서비스 등록 (서비스명: hello_world.say_hello)
    hass.services.async_register(DOMAIN, "say_hello", handle_say_hello)

    # True를 반환해야 HA가 "로드 성공"으로 판단함
    return True

• 코드 해설:
  • async_setup: HA가 configuration.yaml에서 이 컴포넌트를 발견하면 가장 먼저 실행하는 함수입니다.
  • hass: Home Assistant의 모든 기능(기기 제어, 상태 읽기 등)에 접근할 수 있는 핵심 객체입니다.
  • hass.services.async_register: 나만의 서비스를 등록합니다. 이제 자동화나 스크립트에서 hello_world.say_hello를 부를 수 있습니다.

5. [실습 3] 설정 파일 등록 및 재시작

이제 HA에게 이 컴포넌트를 로드하라고 알려줍니다.

1. /config/configuration.yaml 파일을 엽니다.
2. 아래 한 줄을 추가합니다.

YAML

 

hello_world:

1. [개발자 도구] > [YAML] > [구성요소 확인]을 누릅니다. (오류가 없어야 합니다.)
2. HA를 **'재시작'**합니다.

6. [결과 확인] 내가 만든 코드의 작동

HA가 재부팅된 후, 다음을 확인해 보세요.

1. 알림 확인: HA 좌측 하단 '알림' 종 모양을 누릅니다. "안녕하세요! 커스텀 컴포넌트가 성공적으로 로드되었습니다."라는 메시지가 떠 있나요? 축하합니다! 여러분의 코드가 실행된 것입니다.
2. 서비스 호출: [개발자 도구] > [서비스] 탭으로 이동합니다.
   • 서비스 검색: hello_world.say_hello
   • 데이터 입력 (YAML 모드):
   • YAML

      

     name: "개발자"
     

   • [서비스 호출] 버튼 클릭.
3. 반응 확인: 다시 알림 창을 보면, "반갑습니다, 개발자님!..."이라는 메시지가 떴을 것입니다.

7. 여기서 어디로 가야 하는가? (확장)

이것은 아주 작은 시작일 뿐입니다. 파이썬을 알면 이제 무엇이든 할 수 있습니다.

• 외부 API 연동: 파이썬의 aiohttp 라이브러리를 이용해 주식 정보, 날씨 정보, 공공 데이터를 가져와 HA 센서(sensor.py 추가 필요)로 만들 수 있습니다.
• 복잡한 제어: hass.states.get('sensor.temp')로 온도를 읽어와서 복잡한 수식을 계산한 뒤 hass.services.call(...)로 에어컨을 제어할 수 있습니다.
• HACS 배포: 이렇게 만든 컴포넌트를 GitHub에 올리고 HACS에 등록하면, 전 세계 사람들이 여러분이 만든 기능을 사용할 수 있습니다.

8. 50편의 대장정을 마치며: 당신은 이제 '메이커(Maker)'입니다

이것으로 Home Assistant 대장정 50편이 모두 끝났습니다.

우리는 1편에서 '소비자'로 시작했습니다. 남들이 만든 제품을 사서 연결했죠. 30편 즈음엔 '관리자'가 되었습니다. 시스템을 최적화하고 네트워크를 설계했습니다. 그리고 오늘, 50편에서 우리는 비로소 **'창조자(Maker)'**가 되었습니다.

Home Assistant는 단순한 '스마트홈 허브'가 아닙니다. 여러분의 상상력을 현실 공간에 구현할 수 있게 해주는 가장 강력한 **'도화지'**입니다.

이 시리즈는 여기서 끝나지만, 여러분의 코드는 이제 시작입니다. 불편함을 발견하고, 코드를 작성하고, 세상을(적어도 여러분의 집을) 더 낫게 만드세요.

그동안 **[블로그 이름]**의 Home Assistant 가이드를 사랑해 주셔서 감사합니다. 여러분의 스마트홈이 언제나 가장 안전하고, 편리하고, 흥미로운 공간이 되기를 진심으로 응원합니다.