ha-configuration

Home Assistant Configuration

When to Use This Skill

Use this skill when...	Use ha-automations instead when...
Editing configuration.yaml	Creating automation rules
Setting up integrations	Writing automation triggers/actions
Managing secrets.yaml	Debugging automation logic
Organizing with packages	Working with automation blueprints
Troubleshooting config errors	Setting up device triggers

Core Configuration Files

File	Purpose
configuration.yaml	Main configuration entry point
secrets.yaml	Sensitive values (passwords, API keys, tokens)
automations.yaml	Automation rules (usually UI-managed)
scripts.yaml	Reusable script sequences
scenes.yaml	Scene definitions
customize.yaml	Entity customizations
packages/*.yaml	Modular configuration packages

Configuration Structure

Basic configuration.yaml

homeassistant:
  name: Home
  unit_system: metric
  time_zone: Europe/Helsinki
  currency: EUR
  country: FI

  # External files
  customize: !include customize.yaml
  packages: !include_dir_named packages/

# Core integrations
default_config:

# Text-to-speech
tts:
  - platform: google_translate

automation: !include automations.yaml
script: !include scripts.yaml
scene: !include scenes.yaml

Secrets Management

secrets.yaml:

# API keys
openweathermap_api_key: "abc123def456"
spotify_client_id: "your_client_id"
spotify_client_secret: "your_client_secret"

# Database
recorder_db_url: "postgresql://user:pass@localhost/hass"

# MQTT
mqtt_username: "homeassistant"
mqtt_password: "secure_password"

# Network
latitude: 60.1699
longitude: 24.9384

Reference in configuration.yaml:

weather:
  - platform: openweathermap
    api_key: !secret openweathermap_api_key

recorder:
  db_url: !secret recorder_db_url

Include Directives

Directive	Description	Example
!include	Include single file	!include automations.yaml
!include_dir_list	Include files as list items	!include_dir_list sensors/
!include_dir_named	Include files as named mappings	!include_dir_named packages/
!include_dir_merge_list	Merge files into single list	!include_dir_merge_list automations/
!include_dir_merge_named	Merge files into single mapping	!include_dir_merge_named integrations/
!secret	Reference from secrets.yaml	!secret api_key
!env_var	Environment variable	!env_var DB_PASSWORD

Package Organization

Packages allow modular configuration by domain:

packages/climate.yaml:

climate_package:
  sensor:
    - platform: template
      sensors:
        average_indoor_temp:
          friendly_name: "Average Indoor Temperature"
          unit_of_measurement: "°C"
          value_template: >-
            {{ (states('sensor.living_room_temp') | float +
                states('sensor.bedroom_temp') | float) / 2 | round(1) }}

  automation:
    - alias: "Climate - AC Auto Off"
      trigger:
        - platform: numeric_state
          entity_id: sensor.average_indoor_temp
          below: 22
      action:
        - service: climate.turn_off
          target:
            entity_id: climate.living_room_ac

  script:
    climate_cool_down:
      alias: "Cool Down House"
      sequence:
        - service: climate.set_temperature
          target:
            entity_id: climate.living_room_ac
          data:
            temperature: 20
            hvac_mode: cool

packages/presence.yaml:

presence_package:
  input_boolean:
    guest_mode:
      name: "Guest Mode"
      icon: mdi:account-multiple

  binary_sensor:
    - platform: template
      sensors:
        anyone_home:
          friendly_name: "Anyone Home"
          device_class: presence
          value_template: >-
            {{ is_state('person.user1', 'home') or
               is_state('person.user2', 'home') or
               is_state('input_boolean.guest_mode', 'on') }}

Common Integration Patterns

MQTT Configuration

mqtt:
  broker: !secret mqtt_broker
  port: 1883
  username: !secret mqtt_username
  password: !secret mqtt_password
  discovery: true
  discovery_prefix: homeassistant

  sensor:
    - name: "Outdoor Temperature"
      state_topic: "sensors/outdoor/temperature"
      unit_of_measurement: "°C"
      device_class: temperature
      value_template: "{{ value_json.temperature }}"

REST Sensors

sensor:
  - platform: rest
    name: "GitHub Stars"
    resource: https://api.github.com/repos/home-assistant/core
    value_template: "{{ value_json.stargazers_count }}"
    scan_interval: 3600
    headers:
      Authorization: !secret github_token

Template Sensors

template:
  - sensor:
      - name: "Sun Elevation"
        unit_of_measurement: "°"
        state: "{{ state_attr('sun.sun', 'elevation') | round(1) }}"

      - name: "Daylight Hours"
        unit_of_measurement: "hours"
        state: >-
          {% set sunrise = as_timestamp(state_attr('sun.sun', 'next_rising')) %}
          {% set sunset = as_timestamp(state_attr('sun.sun', 'next_setting')) %}
          {{ ((sunset - sunrise) / 3600) | round(1) }}

  - binary_sensor:
      - name: "Workday"
        state: "{{ now().weekday() < 5 }}"

Input Helpers

input_boolean:
  vacation_mode:
    name: "Vacation Mode"
    icon: mdi:airplane

input_number:
  target_temperature:
    name: "Target Temperature"
    min: 16
    max: 28
    step: 0.5
    unit_of_measurement: "°C"
    icon: mdi:thermometer

input_select:
  house_mode:
    name: "House Mode"
    options:
      - Home
      - Away
      - Sleep
      - Guest
    icon: mdi:home

input_text:
  notification_message:
    name: "Custom Notification"
    max: 255

input_datetime:
  alarm_time:
    name: "Alarm Time"
    has_date: false
    has_time: true

Configuration Validation

Check Configuration

# Docker/Container
docker exec homeassistant hass --script check_config

# Home Assistant OS
ha core check

# Supervised
hassio homeassistant check

# Python venv
hass --script check_config -c /path/to/config

Common Validation Errors

Error	Cause	Fix
found undefined alias	Missing !secret value	Add to secrets.yaml
could not determine a constructor	Invalid YAML syntax	Check indentation
duplicate key	Same key defined twice	Remove duplicate
Platform not found	Missing integration	Install via UI/HACS

Recorder Configuration

recorder:
  db_url: !secret recorder_db_url
  purge_keep_days: 10
  commit_interval: 1

  exclude:
    domains:
      - automation
      - updater
    entity_globs:
      - sensor.weather_*
    entities:
      - sun.sun
      - sensor.date

  include:
    domains:
      - sensor
      - binary_sensor
      - switch

Logger Configuration

logger:
  default: warning
  logs:
    homeassistant.core: info
    homeassistant.components.mqtt: debug
    custom_components.my_integration: debug
    # Reduce noise
    homeassistant.components.websocket_api: error

Lovelace Dashboard (YAML Mode)

# configuration.yaml
lovelace:
  mode: yaml
  resources:
    - url: /hacsfiles/button-card/button-card.js
      type: module
  dashboards:
    lovelace-home:
      mode: yaml
      filename: dashboards/home.yaml
      title: Home
      icon: mdi:home
      show_in_sidebar: true

Quick Reference

YAML Tips

Pattern	Example
Multi-line string	value: >- or value: |-
List item	- item
Inline list	[item1, item2]
Comment	# comment
Anchor	&anchor_name
Reference	*anchor_name
Merge	<<: *anchor_name

Template Syntax

Function	Example
State value	states('sensor.temp')
State attribute	state_attr('sun.sun', 'elevation')
Convert to float	states('sensor.temp') | float
Round	value | round(1)
Default value	states('sensor.x') | default('unknown')
Timestamp	as_timestamp(now())
Time delta	now() - timedelta(hours=1)

Agentic Optimizations

Context	Command
Validate config	docker exec homeassistant hass --script check_config 2>&1 | head -50
Find entity usage	grep -r "entity_id:" config/ --include="*.yaml"
Find secret refs	grep -r "!secret" config/ --include="*.yaml"
List packages	ls -la config/packages/
Check YAML syntax	python3 -c "import yaml; yaml.safe_load(open('file.yaml'))"