Перейти к содержимому
ESPHome Flasher

Структура обычного конфига ESPHome

Структура обычного конфига ESPHome

Гайд про один файл .yaml (или несколько через !include), без .j2. Официальная справка по каждому компоненту — на esphome.io; здесь — карта блоков и практичный порядок секций.

Рекомендуемый порядок секций

Сверху вниз — от «инфраструктуры» к «логике устройства». Так проще читать и диффить.

  1. substitutions (если есть повторяющиеся строки/пины).
  2. esphome: — имя узла, отображаемое имя, проект, при необходимости on_boot, build_path.
  3. Платформа: esp32: / esp8266: — плата, фреймворк (esp-idf или arduino).
  4. Сеть: wifi:, captive_portal:, при необходимости improv_serial:.
  5. Сервисы: logger:, api:, ota:.
  6. Шины / железо: i2c:, spi:, uart:, one_wire: — по факту подключения.
  7. Периферия и логика: сенсоры, реле, свет, скрипты, interval, globals.
  8. Диагностика: text_sensor версии, sensor RSSI/uptime — в конце или отдельным !include.

Ядро: esphome:

ПолеНазначение
nameТехническое имя узла (hostname .local, префикс сущностей). Стабильное после первого подключения к HA.
friendly_nameЧеловекочитаемое имя в Home Assistant.
project.name / project.versionМетаданные прошивки (удобно для OTA и отладки).
min_versionМинимальная версия ESPHome для этого конфига.
on_bootДействия при старте (осторожно с тяжёлыми lambda на раннем boot).
esphome:
  name: kitchen-sensor
  friendly_name: Кухня · датчик
  min_version: 2026.4.0
  project:
    name: my.home.kitchen-sensor
    version: "1.0.0"

Платформа: esp32: / esp8266:

Задаёт SoC и сборку. Для ESP32 часто esp-idf; для простых конфигов на классических чипах — arduino.

esp32:
  board: esp32-c6-devkitc-1
  framework:
    type: esp-idf

Сеть

wifi:

STA (домашняя сеть) и/или ap: (точка доступа для первичной настройки). !secret — из secrets.yaml рядом с конфигом.

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: "kitchen-sensor-fallback"
    password: !secret ap_password
  reboot_timeout: 0s

captive_portal:

Веб-портал при активном AP — удобно ввести Wi‑Fi без перепрошивки.

improv_serial:

Настройка Wi‑Fi через USB с web.esphome.io (Improv).

Логи и API

logger:

Уровень логов, часто baud_rate / hardware_uart на ESP32 с USB-JTAG.

logger:
  level: INFO

api:

Связь с Home Assistant. encryption.key обязателен для безопасного канала.

api:
  encryption:
    key: !secret api_encryption_key

ota:

Обычно несколько платформ: нативный ESPHome + при необходимости http_request для кастомного OTA.

ota:
  - platform: esphome
    password: !secret ota_password
  - platform: http_request

Поток обновлений и манифесты в этом репозитории — Обзор OTA и быстрый старт.

HTTP и веб

http_request:

Клиент для GET/POST (проверка latest.json, вызовы внешних API). Задаёт таймауты и useragent.

web_server:

Локальная веб-морда на устройстве (опционально, увеличивает размер прошивки).

Шины и низкоуровневое железо

Кратко: объявляются один раз, дальше сенсоры ссылаются на id.

БлокРоль
i2c:Датчики и чипы по I²C (SCL/SDA).
spi:Дисплеи, радиомодули.
uart:UART-устройства, модбас, радары.
one_wire:DS18B20 и аналоги.

Сущности Home Assistant

Каждый элемент списка — будущая сущность в HA (если не internal / скрыт).

sensor:

Измеряемые величины: температура, напряжение, RSSI.

sensor:
  - platform: wifi_signal
    name: "WiFi RSSI"
    update_interval: 60s

binary_sensor:

Два состояния: кнопка, геркон, PIR, «мало воды».

binary_sensor:
  - platform: gpio
    pin: GPIO4
    name: "Дверь"
    device_class: door

switch: / output:

Управление нагрузкой. switch часто на базе gpio или шаблона.

light: / fan: / climate:

Свет (в т.ч. addressable), вентиляторы, климат (зависят от железа).

button: / number: / select:

Кнопки сценариев, числовые настройки, выбор режима.

text_sensor:

Текстовые строки: версия, статус, диагностика.

Логика без HA-автоматизаций

script:

Именованные сценарии с шагами then:, режимы single / restart / queued.

script:
  - id: blink_led
    then:
      - light.turn_on: status_led
      - delay: 200ms
      - light.turn_off: status_led

interval:

Периодический запуск действий (опрос, watchdog, фоновые проверки).

interval:
  - interval: 10s
    then:
      - logger.log: heartbeat

globals:

Переменные в RAM/NVS между перезагрузками (restore_value), удобно для флагов и FSM.

Вспомогательное

БлокЗачем
time:Синхронизация времени (Home Assistant, SNTP).
preferences: / on_safe_shutdownРедко в простых проектах; тонкая настройка flash/NVS.
external_components:Подключение компонентов с GitHub (например Zigbee).
packages:Сборка конфига из переиспользуемых фрагментов.

secrets.yaml

Рядом с основным YAML (или путь в CLI). Типичные ключи в этом проекте:

  • wifi_ssid, wifi_password, ap_password
  • api_encryption_key, ota_password

Минимальный рабочий скелет

esphome:
  name: demo-node
  friendly_name: Demo


esp32:
  board: esp32-c3-devkitm-1
  framework:
    type: esp-idf


logger:
  level: INFO


api:
  encryption:
    key: !secret api_encryption_key


ota:
  - platform: esphome
    password: !secret ota_password


wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password


captive_portal:


sensor:
  - platform: uptime
    name: Uptime

Дальше