ESPHome 통합기능을 사용하면 ESPHome 기기를 네이티브 ESPHome API를 통해 Home Assistant에 직접 연결할 수 있습니다. 이 문서는 ESPHome 기기를 Home Assistant에 설정하고 사용하는 방법을 안내합니다.

1. Home Assistant가 자동으로 ESPHome 기기를 검색할 수 있습니다.
2. 기기가 발견되면 "Discovered"로 표시됩니다.
3. 즉시 설정을 진행할 수 있습니다.

자동으로 검색되지 않을 경우, 다음 단계를 따라 수동으로 설정할 수 있습니다:

1. Home Assistant 인스턴스에 접속합니다.
2. Settings(설정) > Devices & Services(기기 및 서비스)로 이동합니다.
3. 우측 하단의 "Add Integration"(통합 추가) 버튼을 선택합니다.
4. 목록에서 "ESPHome"을 선택합니다.
5. 화면의 지시사항에 따라 설정을 완료합니다.

• ESPHome 기기는 모든 Home Assistant 작업을 수행할 수 있습니다.
• 이 기능은 새로 구성된 기기에서 기본적으로 비활성화되어 있습니다.
• 각 기기별로 옵션 설정을 통해 활성화할 수 있습니다.

1. Home Assistant 인스턴스에 접속합니다.
2. Settings > Devices & Services로 이동합니다.
3. 여러 ESPHome 인스턴스가 구성된 경우 설정하려는 인스턴스를 선택합니다.
4. 통합을 선택한 후 "Configure"를 선택합니다.

• ESPHome configuration.yaml에서 friendly_name을 설정하는 것을 권장합니다.
• 엔티티 이름은 친숙한 이름과 구성요소 이름의 조합입니다.
• 엔티티 ID는 기기 이름이 앞에 추가된 엔티티 이름에서 파생됩니다.

예시 구성:

esphome:
   name: "livingroomdesk"
   friendly_name: "Living room desk"

sensor:
   name: "Temperature"

결과:

• 엔티티 이름: "Living room desk Temperature"
• 엔티티 ID: "sensor.livingroomdesk_temperature"

friendly_name이 설정되지 않은 경우 적용되는 방식입니다:

• 엔티티 이름은 구성요소 이름입니다.
• 기기 이름은 엔티티 이름에 추가되지 않습니다.
• 엔티티 ID는 엔티티 이름에서만 파생됩니다.

예시 구성:

esphome:
   name: "livingroomdesk"

sensor:
   name: "Temperature"

결과:

• 엔티티 이름: "Temperature"
• 엔티티 ID: "sensor.temperature"

• Home Assistant 0.85 버전부터 도입되었습니다.
• 활성 설치의 24.5%에서 사용되고 있습니다.
• IoT 클래스: Local Push
• 품질 등급: Platinum
• 로컬 네트워크를 통해 Home Assistant와 작동합니다.

• 문제가 발생할 경우 GitHub에서 이슈를 확인하거나 보고할 수 있습니다.
• 자세한 기술 문서는 ESPHome 공식 문서를 참조하십시오.

MQTT(Message Queuing Telemetry Transport)는 TCP/IP 기반의 경량 메시징 프로토콜로, IoT 기기들 간의 통신에 널리 사용됩니다. Home Assistant와의 통합을 통해 다양한 IoT 기기들을 효과적으로 제어할 수 있습니다.

1. 자동 설정 (권장)

   • Mosquitto Broker 애드온 설치
   • MQTT 통합 구성 시 자동으로 안전한 사용자명과 비밀번호 생성
   • 추가 로그인은 Mosquitto 애드온 설정에서 구성 가능

2. 수동 설정

   • Settings > Devices & Services 이동
   • Add Integration 버튼 클릭
   • MQTT 선택
   • 화면의 지시에 따라 설정 완료

고급 설정에 접근하려면:

1. Settings > Devices & Services로 이동
2. MQTT 통합 선택
3. Configure 선택 후 Re-configure MQTT 선택
4. Advanced options 활성화

주요 고급 설정 옵션:

• 커스텀 클라이언트 ID 설정
• 클라이언트 인증서 설정
• 브로커 인증서 검증
• MQTT 프로토콜 버전 선택 (3.1.1 또는 5)
• WebSocket 전송 설정

• 기본적으로 활성화되어 있음
• 최소한의 설정으로 MQTT 기기 사용 가능
• 검색 토픽 형식: <discovery_prefix>/<component>/[<node_id>/]<object_id>/config

{
  "dev": {
    "ids": "고유ID",
    "name": "기기이름",
    "mf": "제조사",
    "mdl": "모델명",
    "sw": "소프트웨어버전"
  },
  "o": {
    "name": "애플리케이션이름",
    "sw": "소프트웨어버전",
    "url": "지원URL"
  },
  "state_topic": "상태토픽",
  "command_topic": "명령토픽",
  "unique_id": "엔티티고유ID"
}

YAML에서 두 가지 스타일로 구성 가능:

1. 항목별 나열 방식

mqtt:
  - binary_sensor:
      name: "센서1"
      state_topic: "home/sensor1"
  - switch:
      name: "스위치1"
      command_topic: "home/switch1"

2. 도메인별 그룹화 방식

mqtt:
  binary_sensor:
    - name: "센서1"
      state_topic: "home/sensor1"
    - name: "센서2"
      state_topic: "home/sensor2"

{
   "name": null,
   "device_class": "motion",
   "state_topic": "homeassistant/binary_sensor/garden/state",
   "unique_id": "motion01ad",
   "device": {
      "identifiers": ["01ad"],
      "name": "정원"
   }
}

{
   "device_class": "temperature",
   "state_topic": "homeassistant/sensor/bedroom/state",
   "unit_of_measurement": "°C",
   "value_template": "{{ value_json.temperature}}",
   "unique_id": "temp01ae",
   "device": {
      "identifiers": ["bedroom01ae"],
      "name": "침실"
   }
}

automation:
  alias: "도착 시 메시지 전송"
  triggers:
    - trigger: state
      entity_id: device_tracker.me
      to: "home"
  actions:
    - action: mqtt.publish
      data:
        topic: "home/notification"
        payload: "집에 도착했습니다"
        retain: true

logger:
  default: warning
  logs:
    homeassistant.components.mqtt: debug

1. 브로커 재설치 시 반드시 추가 로그인 정보 백업
2. 자동 검색 사용 시 고유 ID 설정 권장
3. 상태 토픽에는 가능한 retain 플래그 사용
4. 보안을 위해 항상 사용자 인증 설정

• ESPHome
• Zigbee2MQTT
• Tasmota
• OpenMQTTGateway
• 기타 다수의 통합 도구 지원

Configuration.yaml은 Home Assistant의 핵심 설정 파일입니다. 대부분의 설정은 UI를 통해 가능하지만, 일부 통합 기능은 이 파일을 직접 편집해야 합니다.

1. Home Assistant Operating System 사용자

   • File editor 애드온 설치 (초보자 추천)
   • Studio Code Server 애드온 설치 (고급 기능 필요 시)
   • Samba 애드온 설치 (로컬 편집기 사용 시)

2. Home Assistant Supervised 사용자

   • File editor 애드온
   • Studio Code Server 애드온
   • Samba 애드온

3. Home Assistant Container/Core 사용자

   • 직접 파일시스템 접근

설치 방식별 기본 위치:

• Operating System: /config 폴더
• Container: 마운트된 config 폴더
• Core: ~/.homeassistant (기본값)

설정 디렉토리 확인 방법:

1. Settings > System > Repairs 이동
2. 우측 상단 메뉴(점 3개) > System information 선택
3. Configuration directory 항목 확인

• 설정 변경 후 자동으로 검사됨
• Home Assistant 재시작 시 자동 검사
• 수동 검사 가능 (설치 유형별 방법 상이)

1. Operating System: 시스템 패널에서 검사
2. Supervised: 관리자 패널에서 검사
3. Container: Docker 명령어로 검사
4. Core: 커맨드라인에서 검사

1. Settings 메뉴로 이동
2. 우측 상단 메뉴(점 3개) 선택
3. Restart Home Assistant > Quick reload 선택

설정이 적용되지 않을 경우:

1. Settings 메뉴로 이동
2. Restart Home Assistant 선택
   • 주의: 자동화와 스크립트가 중단됨

1. 구문 오류 확인
2. 들여쓰기 확인 (YAML은 들여쓰기에 민감)
3. 로그 확인
4. 백업 유지

# 올바른 예시
light:
  - platform: mqtt
    name: "거실등"
    state_topic: "home/light/status"

# 잘못된 예시
light:
- platform: mqtt
  name: "거실등"
    state_topic: "home/light/status"  # 들여쓰기 불일치

큰 설정 파일을 관리하기 쉽게 분할할 수 있습니다:

# configuration.yaml
homeassistant:
  packages: !include_dir_named packages

# 분할된 설정 파일들은 packages/ 디렉토리에 저장

민감한 정보는 별도의 secrets.yaml 파일에 저장:

# secrets.yaml
mqtt_password: "your_secret_password"

# configuration.yaml
mqtt:
  password: !secret mqtt_password

1. 변경 전 항상 백업
2. 작은 단위로 변경 후 테스트
3. 주석 활용하여 설정 문서화
4. 정기적으로 설정 검증
5. 중요 변경 시 전체 재시작 권장

• YAML 문법
• 백업 생성 및 복원
• 개발자 도구를 통한 YAML 설정 리로드
• 파일 접근 설정
• 보안 설정

• 위치: configuration 디렉토리의 home-assistant.log 파일
• 로그 파일은 Home Assistant 시작 시 초기화됨
• 모든 경고와 오류 메시지가 기록됨

1. home-assistant.log 파일에서 관련 오류 확인
2. 설정 파일의 구문 오류 확인
3. 필수 종속성 설치 여부 확인
4. Home Assistant 재시작 시도

1. UTF-8 인코딩 확인
2. YAML 구문 검증
3. 중복 섹션 확인
4. 필수 설정 누락 확인

# 올바른 구성 예시
sensor:
  - platform: forecast
    ...
  - platform: bitcoin
    ...

# 잘못된 구성 예시 (중복 섹션)
sensor:
  platform: forecast
    ...
sensor:
  platform: bitcoin
    ...

# configuration.yaml
light: !include devices/lights.yaml
sensor: !include devices/sensors.yaml

# lights.yaml
- platform: hyperion
  host: 192.168.1.98
  
# sensors.yaml
- platform: mqtt
  name: "방 습도"
  state_topic: "room/humidity"

유효한 문자:

• 소문자
• 숫자
• 밑줄(_)

주의사항:

• 밑줄로 시작하거나 끝나면 안 됨
• 다른 특수문자 사용 불가
• UI에서 자동 검증됨

1. Settings > Devices & services 이동
2. 문제가 있는 통합구성 카드 선택
3. 'Enable Debug Logging' 선택
4. 오류 재현
5. 'Disable Debug Logging' 선택하여 로그 파일 다운로드

1. 통합구성 상세 페이지에서 메뉴(점 3개) 선택
2. 'Download Diagnostics' 선택
3. 진단 파일 저장

디버그 모드 활성화:

# configuration.yaml
homeassistant:
  debug: true

주의: 성능에 영향을 줄 수 있으므로 장기 사용은 권장하지 않음

1. Home Assistant 재시작
2. 로그에서 구체적인 오류 확인
3. 필요한 패키지 수동 설치
4. 재시작 후 재확인

1. 디버그 로그 파일
2. 진단 정보 파일
3. 설정 파일 관련 내용
4. 오류 재현 방법
5. Home Assistant 버전 정보

logger:
  default: warning
  logs:
    homeassistant.components.문제_컴포넌트: debug

심각한 문제 발생 시 안전 모드로 시작하여 문제 해결:

1. Home Assistant 중지
2. 설정 파일 백업
3. 최소 설정으로 시작
4. 단계적으로 설정 추가

1. 로그 모니터링
2. 리소스 사용량 확인
3. 불필요한 통합구성 비활성화
4. 자동화 규칙 최적화

# configuration.yaml 핵심 구성
homeassistant:
  # Home Assistant 인스턴스 이름
  name: "내 홈어시스턴트"
  # 일출/일몰 계산을 위한 위치 정보
  latitude: 37
  longitude: 127
  # 단위 시스템 ('metric' 또는 'us_customary')
  unit_system: metric
  # 시간대 설정
  time_zone: "Asia/Seoul"
  # 사용자 정의 설정 포함
  customize: !include customize.yaml

주요 기능별로 파일 분리:

# configuration.yaml
automation: !include automation.yaml
zone: !include zone.yaml
sensor: !include sensor.yaml
switch: !include switch.yaml
device_tracker: !include device_tracker.yaml

4가지 고급 include 옵션:

1. !include_dir_list

   • 디렉토리의 내용을 리스트로 반환
   • 파일명 알파벳 순으로 정렬

   # configuration.yaml
   automation: !include_dir_list automation/presence/

2. !include_dir_named

   • 디렉토리 내용을 파일명 기준 사전으로 반환

   # configuration.yaml
   alexa:
     intents: !include_dir_named alexa/

3. !include_dir_merge_list

   • 여러 파일의 리스트를 하나로 병합

   # configuration.yaml
   automation: !include_dir_merge_list automation/

4. !include_dir_merge_named

   • 여러 파일의 설정을 하나의 사전으로 병합

   # configuration.yaml
   group: !include_dir_merge_named group/

# automation/lights/
# turn_light_on.yaml
alias: "조명 켜기"
triggers:
  - platform: sun
    event: sunset
actions:
  - service: light.turn_on
    target:
      entity_id: light.living_room

# turn_light_off.yaml
alias: "조명 끄기"
triggers:
  - platform: sun
    event: sunrise
actions:
  - service: light.turn_off
    target:
      entity_id: light.living_room

# groups/interior.yaml
거실:
  name: "거실"
  entities:
    - light.living_room
    - media_player.tv
    - climate.living_room

침실:
  name: "침실"
  entities:
    - light.bedroom
    - climate.bedroom

# sensors/environmental.yaml
- platform: temperature
  name: "거실 온도"
  entity_id: sensor.living_room_temp

- platform: humidity
  name: "거실 습도"
  entity_id: sensor.living_room_humidity

• 기본 들여쓰기: 2칸
• 리스트 항목: 하이픈(-) 다음 1칸
• 잘못된 들여쓰기는 오류의 주요 원인

• .yaml 확장자만 지원
• .yml은 지원되지 않음

### 조명 자동화 ###############
- platform: light
  name: living_room
  # 거실 메인 조명
  entities:
    - light.ceiling
    - light.table_lamp

### 센서 설정 ################
- platform: temperature
  # 온도 센서 설정

# configuration.yaml
# 수동 작성 자동화
automation manual: !include_dir_merge_list automations/

# UI에서 생성한 자동화
automation ui: !include automations.yaml

1. Home Assistant 설정 검사 도구 사용
2. YAML 문법 검사기 활용
3. 로그 파일 확인

• 들여쓰기 불일치
• 파일 경로 오류
• 중복된 설정
• 잘못된 참조

1. 논리적인 파일 구조 유지
2. 명확한 파일 이름 사용
3. 주석으로 설정 문서화
4. 정기적인 백업 유지
5. 변경 사항 단계적 적용