Home Assistant MQTT 템플릿과 센서 자동화 심화

서론: 왜 MQTT 템플릿이 중요한가

Home Assistant에서 MQTT는 센서와 장치의 가교 역할을 한다. 특히 템플릿을 적절히 쓰면 수신하는 페이로드를 의미 있는 상태와 속성으로 바꿀 수 있다. 초보자도 이해하기 쉽게 템플릿 기본, Discovery 활용, 센서 자동화 연동까지 단계별로 다룬다.

기본 개념 정리

MQTT 메시지와 페이로드

MQTT는 토픽 기반 통신을 사용한다. 장치는 특정 토픽으로 JSON, 문자열, 숫자 등 페이로드를 전송한다. Home Assistant는 value_template을 통해 이 페이로드를 해석하여 센서의 상태(state)와 속성(attributes)으로 변환한다.

템플릿 문법 요약

Home Assistant 템플릿은 Jinja 문법을 사용한다. 흔히 쓰는 표현은 다음과 같다.

• 간단한 값 추출: {{ value_json.temp }}
• 조건부 처리: {{ value | int > 100 and 'high' or 'normal' }}
• 문자열 처리와 포맷: {{ (value_json.hum * 1.0) | round(1) }}

실습 예제: MQTT 센서 구성

다음 예제는 장치에서 JSON 페이로드를 보내고, Home Assistant가 템플릿으로 값을 추출하는 방식이다.

sensor:
  - platform: mqtt
    name: "온도 센서"
    state_topic: "home/sensor/room1"
    value_template: "{{ value_json.temperature | round(1) }}"
    unit_of_measurement: "°C"
    json_attributes_topic: "home/sensor/room1"
    json_attributes_template: "{\n  \"raw_humidity\": {{ value_json.humidity }},\n  \"battery\": {{ value_json.batt }}\n}"

위 구성에서는 state는 temperature로, 추가 속성은 JSON에서 별도 추출해서 attributes에 담는다. json_attributes_template을 사용하면 필요한 속성만 선택적으로 저장 가능하다.

Discovery를 통한 자동 등록

MQTT Discovery를 이용하면 Home Assistant가 자동으로 센서를 등록한다. 디스커버리 페이로드에도 템플릿을 적용할 수는 없지만, 장치 쪽에서 보낼 페이로드를 잘 설계하면 더 유연한 구성이 가능하다.

topic: "homeassistant/sensor/room1/config"
payload: |
  {"name":"Room1 Temp","state_topic":"home/sensor/room1","unit_of_measurement":"°C","json_attributes_topic":"home/sensor/room1"}

이렇게 구성하면 UI에 자동으로 센서가 나타난다. 이후 동일한 state_topic에 JSON을 보내면 앞서 설정한 템플릿으로 처리된다.

고급 템플릿: 오류와 결측값 처리

현장 데이터는 항상 깔끔하지 않다. 템플릿에서 예외 처리를 해두면 안정성이 높아진다. 예를 들어 값이 null이거나 문자열일 경우 안전하게 변환하는 방법은 다음과 같다.

value_template: "{{ (value_json.temperature if value_json.temperature is not none else '0') | float | round(1) }}"

또는 상태가 숫자가 아닐 때 기본값을 설정하는 방법도 유용하다.

자동화 연동 예제

MQTT 센서 상태를 기반으로 Home Assistant 자동화를 작성하면 현장 제어가 가능하다. 아래는 온도가 28°C 이상일 때 팬을 켜는 간단한 자동화 예이다.

automation:
  - alias: "더울 때 팬 켜기"
    trigger:
      - platform: numeric_state
        entity_id: sensor.온도_센서
        above: 28
    action:
      - service: switch.turn_on
        target:
          entity_id: switch.room_fan

보다 복잡한 흐름에서는 템플릿을 이용해 여러 센서 값을 조합해 조건을 만들 수 있다. 예를 들어 온도와 습도 조합으로 쿨링 모드를 결정하는 식이다.

양방향 통신: 상태 반영과 피드백

센서뿐 아니라 Home Assistant에서 MQTT로 명령을 보내 장치를 제어할 수 있다. 자동화 안에서 mqtt.publish 서비스를 사용하면 된다.

action:
  - service: mqtt.publish
    data:
      topic: "device/room1/command"
      payload: "{\"cmd\": \"set_fan\", \"level\": \"high\"}"

이 방식으로 장치에 피드백을 줄 때도 JSON 구조를 표준화하면 템플릿으로 수신 데이터를 일관되게 처리할 수 있다.

디버깅과 성능 고려사항

• 로그 확인: 템플릿 오류는 로그에 출력된다. 개발 중엔 로그 레벨을 높여 문제를 빠르게 찾는다.
• 토픽 설계: 토픽 네이밍을 체계화하면 필터링과 접근이 쉬워진다.
• 페이로드 크기: 불필요한 속성을 줄이면 네트워크와 HA 처리 부하가 감소한다.
• 유효성 검사: 장치에서 보내는 JSON 스키마를 정의하면 템플릿에서의 예외가 줄어든다.

마무리: 적용 체크리스트

• value_template으로 상태 변환 테스트 완료
• json_attributes_template로 필요한 속성만 추출
• Discovery 사용 시 토픽과 페이로드 일관성 확보
• 자동화 조건에는 안전한 타입 변환과 기본값 설정
• 로그 모니터링으로 템플릿 오류 신속 대응

이 글에서 제시한 예제와 원칙을 따라하면 home assistant mqtt 템플릿을 안정적으로 운영할 수 있다. 초보자는 기본 템플릿과 간단한 자동화로 시작하고, 익숙해지면 json_attributes_template이나 복합 조건 처리를 추가해 확장하면 효과적이다.