Налаштовуємо ESPHome. Посібник для початківців

Привіт. На зв’язку Богдан Свердлюк. Я люблю налаштовувати різні функції в «розумному» будинку і розповідати про це українською. У цій статті поговоримо про те, як налаштувати свою роботу з ESPHome.

Це — відкритий проєкт, що покликаний створювати дешеві Wi-Fi та Bluetooth пристрої без знань мови програмування на основі сімейства Wi-Fi плат ESP8266/ESP32 та RP2040. ESPHome підтримує велику кількість периферійного обладнання, що робить його дуже гнучким та потужним інструментом для DIY розробників та розв’язання побутових задач. російський військовий корабель, пішов нах***!

Як працює ESPHome

ESPHome дозволяє керувати підключеним обладнанням до контролера ESP чи Raspberry RP2040. Для цього перетворює добре зрозумілий конфігурацій файл YAML на файл прошивки (компілює) та завантажує в пам’ять контролера.

Існує декілька сценаріїв використання ESPHome:

1. Створення нового пристрою на основі плат без програмного забезпечення.
2. Перепрошивка пристроїв виробника. До прикладу частим сценарієм є перепрошивка реле Sonoff Basic, Shelly, Tuya та інших.
3. Купівля готових пристроїв для роботи в ESPHome. Такі пристрої можна знайти на AliExpress з позначкою made for ESPHome.

Щодо архітектури роботи, пристрої під керуванням ESPHome можуть працювати як:

• клієнт, що керується Home Assistant без можливості керування через вебінтерфейс;
• клієнт, що керується Home Assistant з можливістю керування через вебінтерфейс;
• незалежний вебсервер з можливістю керування через вебінтерфейс.

Є декілька способів керувати та отримувати стан пристрою ESPHome:

• рекомендованим способом є керування пристроєм ESPHome через Home Assistant. Для цього використовується компонент Native API. Додатково до нього можна увімкнути керування за допомогою MQTT та REST API;
• якщо пристрій працює незалежно можна керувати ним через MQTT;
• якщо пристрій працює незалежно можна керувати ним через REST API.

Що можна зробити з ESPHome

ESPHome може створити майже будь-який пристрій IoT. Ось декілька прикладів. Конкретні приклади дивись нижче у розділі цієї статті цікаві проєкти.

Керування сенсорами дозволяє приєднувати до ESP та RPI велику кількість цифрових та аналогових сенсорів. Детальніше про сенсори — на сторінці ESPHome. До них входять сенсори руху, температури, вологості, якості повітря, різноманітних газів, відстані, потужності, струму, світла та багато інших. Детальніше на головній сторінці ESPHome.

Відстеження пристроїв iBeacon. iBeacon або маячки — це маленькі Bluetooth Low Energy (BLE) пристрої на батарейках, що дозволяють пристроям постійно надсилати заздалегідь визначений пакет даних.

Варіанти використання:

• відстеження відстані до пристрою всередині приміщення.Наприклад, до ключів;
• відстеження присутності людини у приміщені за допомогою смартфону.

Збір інформації з датчиків Xiaomi BLE. Дозволяє збирати дані BLE датчиків Xiaomi, інтегрувати їх в Home Assistant та використовувати без застосунку Mi Home. Це значить, що можна переглядати показники не лише коли вдома, але і дистанційно. Ця інтеграція лише прослуховує пакети та не керує BLE пристроями. Детальніше тут.

Керування освітленням ESPHome дозволяє керувати як звичайними, так і адресними світлодіодним стрічками, Wi-Fi лампами, димуванням, білим, холодним, монохроматичним освітленням, яскравістю та кольором.

Керування дисплеями дозволяє відображати дані на електронному папері, LCD, сегментних та інших цифрових дисплеях.

Керування реле дозволяє вмикати, вимикати пристрої, отримувати дані по сухому контакту, проводити енергомоніторинг, димування світла.

Керування сервоприводами та кроковими двигунами дозволяє створювати різноманітні рухомі механізми з обертальним та круговим рухом.

Керування звуком дозволяє під’єднувати динаміки (часто за допомогою шини I2C), п’єзоелемент.

Як встановити ESPHome

Home Assistant

ESPHome належить компанії, що розроблює Home Assistant — Nabu Casa. Тому популярним способом є встановлення ESPHome як застосунку у цій операційній системі.

Для встановлення ESPhome в Home Assisatnt перейдіть у бічне меню >> Застосунки >> Магазин >> у пошуку введіть ESPHome. Встановіть та запустіть.

Також можна використовувати ESPHome повністю незалежно від Home Assistant, що робить його ідеальним вибором для розробки пристрою IoT, якому не потрібен сервер.

Python

Щоб встановити ESPHome як Python-програму, спочатку встановіть Python. Після у терміналі або CMD, та встановіть ESPHome:

pip3 install wheel
pip3 install esphome

Запустіть майстер налаштувань:

esphome web_control.yaml wizard

де web_control — довільна назва вашого файлу. Буде створено файл конфігурації у папці, де ви зараз находитесь. Після можна відредагувати файл за допомогою зручного для вас редактора, наприклад, VSCode, або Notepad ++.

Після того як прошивка пристрою буде написана, можна її завантажити на пристрій. Перше завантаження прошивки завжди виконується кабелем, наступні можна завантажувати уже бездротово. Для першої прошивки підключіть плату до комп’ютера, де запущено ESPHome, та виконайте команду:

esphome run web_control.yaml

Встановлення інформаційної панелі:

pip install tornado esptool esphome dashboard config/

Після введіть адресу пристрою, на якому встановлено Docker та порт 6052. Наприклад 192.168.0.2:6052.

Docker

Для використання ESPHome як Docker-контейнер, встановіть Docker. У терміналі або CMD встановіть контейнер ESPHome:

docker pull esphome/esphome

Після запустіть майстер налаштувань ESPHome.

docker run —rm -v "${PWD}":/config -it esphome/esphome wizard livingroom.yaml

де livingroom — довільна назва файлу. Буде створено файл конфігурації у папці, де ви зараз знаходитесь. Після можна відредагувати файл за допомогою зручного для вас редактора, наприклад, VSCode або Notepad ++.

Після того, як прошивка пристрою буде написана, можна її завантажити на пристрій. Перше завантаження прошивки завжди виконується кабелем, наступні можна завантажувати уже бездротово. Для першої прошивки підключіть плату до комп’ютера, де запущено Docker, за допомогою USB-кабелю. Запустіть команду:

esphome run livingroom.yaml

На Linux команда повинна мати адресу USB-пристрою.

docker run —rm —privileged -v "${PWD}":/config —device=/dev/ttyUSB0 -it esphome/esphome run livingroom.yaml

де /dev/ttyUSB0 — адреса USB-пристрою. Дізнатись весь список пристроїв можна за допомогою команди dmesg | grep ttyUSB

Mac взагалі не може отримати доступ до хост-пристроїв USB. Тому він не може використовуватись для запису першої прошивки з Docker.

Встановлення інформаційної панелі

docker run —rm —net=host -v "${PWD}«:/config -it esphome/esphome

Після введіть адресу пристрою, на якому встановлено Docker та порт 6052. Наприклад6 192.168.0.2:6052.

ESP Web Tools та web.esphome.io

ESP Web Tools та аналогічний web.esphome.io — інструменти, що працюють з браузера. Браузер повинен підтримувати підключення USB пристроїв — Web serial, Google Chrome або Microsoft Edge.

Це, мабуть, найпростіший спосіб встановлення ESPHome. Все, що потрібно зробити — приєднати плату USB кабелем, натиснути connect, обрати порт та ввести дані Wi-Fi мережі. Запис конфігурації займає менш як хвилину.

Інструмент може:

• завантажити лише базову конфігурацію. Це конфігурація для плати без підключених пристроїв. (Prepare for first use) Після приєднання до живлення плата автовизначиться в Home Assistant;
• завантажити готову конфігурацію в форматі .bin.

*Якщо у вас немає Home Assistant, і ви не хочете чи не можете встановити ESPHome на комп’ютер, можна написати та скомпілювати за допомогою сервісу Play with Docker.

Майстер налаштувань

Коли ви встановили ESPHome, є два способи створити новий пристрій:

• за допомогою графічного інтерфейсу інформаційної панелі;
• за допомогою командного рядка. Така можливість є в Python та Docker інсталяцій.

Вперше майстер налаштувань запитає назву та пароль Wi-Fi мережі. При створенні нового пристрою потрібно вказати довільну назву пристрою, обрати платформу та тип плати. Коли пристрій створено, можна заповнювати конфігураційний файл. Для цього в графічному інтерфейсі потрібно натиснути Edit на пристрої.

Якщо пристрій створено за допомогою командного рядка, потрібно знайти створений YAML-файл.

Інтерфейс інформаційної панелі

Коли створюється конфігураційний файл пристрою .yaml, він з’являється в інформаційній панелі. При встановленні застосунку ESPHome, усі конфігурації знаходяться у директорії /config/esphome/. До неї зручно отримати доступ через додаток File Editor або Samba. Для кожного вузла є декілька дій:

• UPDATE — ця кнопка з’явиться, якщо пристрій не оновлено;
• EDIT — відкриває редактор конфігурацій;
• LOGS — за допомогою цієї кнопки можна переглянути всі журнали, які виводить вузол;
• Overflow menu (три крапки) — це випадне меню, яке дозволяє виконувати більше дій;
• Validate — перевіряє правильність конфігурації;
• Install — відкриває діалогове вікно встановлення. Дивись розділ встановлення прошивки;
• Clean Build Files — видалення всіх створених файлів збірки (.bin). Іноді старі файли не видаляються, що може спричинити проблеми з компіляцією пізніше;
• Delete — це видалить файл конфігурації (видалить пристрій).

Configuration YAML

Конфігурація EPHome максимально схожа до Home Assistant configuration.yaml. Майстер налаштувань створює початкову конфігурацію. Після можна додавати блоки роботи з сенсорами чи пристроями.

Наприклад, я хочу керувати лампочкою через 5 вольтове реле. Для цього використовується компонент switch та платформа gpio. Це дозволяє використовувати будь-який пін плати як вимикач.

switch:
  - platform: gpio
    name: "Реле лампа"
    pin: 5

Моя повна конфігурація виглядає ось так:

esphome:
  name: relay
  friendly_name: Relay DOU

esp8266:
  board: nodemcuv2

# Enable logging
logger:
  #level: VERY_VERBOSE

# Enable Home Assistant API
api:
  encryption:
    key: "sE+X65uSDG617KfmnNFPo5k0QRJnnwaziT6jvGK79Ss="

ota:
  password: "b52f42b3beb6f21097ba53c6e79d6fc5"

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

  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "Relay Fallback Hotspot"
    password: "emYvyOMNPYOE"

captive_portal:
   
switch:
  - platform: gpio
    name: "Relay"
    pin: D3

web_server:
  port: 80

Як фізично підключити реле до nodemcu

Для прикладу підключення: я використовую NodeMCU V3 ESP8266 (CH340) та 5В 10A Songle реле з трьома контактами. Проте, яке це буде реле чи ESP — не принципово. Потрібно лише правильно підключити контакти.

Якщо все підключено правильно, при увімкненні та вимкненні реле буде чути клацання. На вихід реле вмикається те, чим потрібно керувати — лампа, вимикач, або поставити в розрив ланцюга перед вилкою.

Встановлення прошивки

Коли конфігурація написана, можна завантажити її на плату. Є декілька способів це зробити:

• за допомогою Wi-FI (OTA);
• за допомогою USB, з’єднаним з будь-яким комп’ютером (необхідна підтримка web serial, ESPHome повинен відкриватись через HTTPS (мати SSL), можливо, необхідно встановити драйвер);
• за допомогою USB до сервера або комп’ютера, де запущено ESPHome;
• завантаження файлу прошивки (.bin) та подальше прошивання за допомогою ESPHome Web.

Успішна компіляція завершується зеленим повідомленням та фіолетовими параметрами плати нижче:

В результаті в інтерфейсі Home Assistant з’явився перемикач switch.relay_rele_lampa. Знайти усі сутності можна в інтерфейсі Home Assistant Налаштування >> Пристрої та сервіси >> вкладка Сутності.

За бажання його можна легко додати на інформаційну панель Home Assistant: Налаштування зведення >> Додати картку >> За сутністю.

Коли увімкнено компонент вебсервер, можна увійти у вебінтерфейс плати за допомогою IP адреси, або mDNS домену <name>.local/; IP-адресу та домен можна знайти, натиснувши на пристрої кнопку Logs.

Ось так виглядає вебінтерфейс плати:

Помилки компіляції

Перед вирішенням будь-якої помилки:

1. Перевірте наявність оновлень.
2. Перезавантажте сервер.

xtensa-lx106-elf-g++: fatal error: Killed signal terminated program cc1plus

compilation terminated.

*** [/data/relay/.pioenvs/relay/src/esphome/components/api/api_pb2.cpp.o] Error 1

Можливо завелике споживання оперативної пам’яті. Перевірити це можна у розділі Налаштування >> Система >> Устаткування.

Зменшити навантаження на оперативну пам’ять можна, якщо вимкнути усі застосунки. Якщо не допоможе, обмежити ESPHome виконанням лише одного процесу (default complete process limit).

Native API

Native API використовується ESPHome та Home Assistant. Він потрібен для спілкування з клієнтами за допомогою високооптимізованого мережевого протоколу.
Рядок api: у конфігураційному файлі дозволяє виявляти пристрої ESPHome у Home Assistant. Якщо використовується базовий конфіг ESPHome WEB, цей рядок уже присутній.

Вебсервер

Щоб увімкнути вебсервер ESPHome до конфігурації YAML потрібно додати рядки:

web_server:
  port: 80

Це дозволяє керувати пристроєм ESPHome за допомогою браузера. Працює з Home Assistant або без нього. За бажання, можна увімкнути вхід за логіном та паролем:

web_server:
  port: 80
  auth:
    username: admin
    password: !secret web_server_password

Рекомендується використовувати ESPHome через Home Assistant, проте додатково можна керувати та отримувати стан пристрою за допомогою REST запитів.

Якщо плата працює незалежно від Home Assistant, можна використовувати REST запити додатково до керування через вебінтерфейс.

Запит пишеться після URL-адреси пристрою за такою схемою:

/<domain>/<id>[/<method>?<param>=<value>]

domain — це, наприклад, тип компонента. Наприклад sensor або light.
id — ідентифікатор компонента. Можна або задати назву id, або дізнатись його з журналу, якщо він не вказаний. Щоб дізнатись ідентифікатор компонента можна встановити рівень журналу VERY_VERBOSE та знайти object_id: у ньому.

Команда для увімкнення реле виглядає так:

http://relay.local/switch/relay/turn_on

для вимкнення так:

http://relay.llocal/switch/relay/turn_off

Є дуже багато інструментів, щоб відправляти REST запити:

• Postman програма на ПК та розширення Chrome;
• Rested розширення Firefox;
• Для iOS та Android можна використовувати різноманітні REST Api Client.

Я використовую Apple команди. Це дуже зручно, можна команду винести на початковий екран як застосунок або віджет.

Інтеграція з MQTT

MQTT — простий та ефективний протокол IoT, що працює за принципом видавець-підписник. Видавець відправляє повідомлення, підписник отримує. Спілкування відбувається у топіках (темах). Теми можна створювати, видаляти, підписуватись та відправляти повідомлення в них. Цим процесом керує брокер.

Mosquitto — один з найпопулярніших брокерів.
MQTT Explorer — корисна програма для дослідження топіків брокера. Компонент MQTT налаштовує підключення до брокера.

Примітка: якщо використовуєте MQTT, не використовуйте Native Api (видаліть стрічку api:), інакше плата перезавантажуватиметься кожні 15 хвилин.

Приклад конфігурації брокера:

mqtt:
  topic_prefix: boat
  discovery: false
  broker: 192.168.1.41
  port: 1883
  username: admin
  password: redacted
  discovery_prefix: homeassistant

Де topic_prefix: тема, в якій будуть публікуватись дані або інші теми з даними.
discovery: (не обов’язкове значення) автовиявлення пристрою в інтерфейсі Home Assistant.
broker: ip адреса брокера.
port: порт брокера.
username: та password: логін та пароль брокера.
discovery_prefix: (не обов’язкове значення) автовиявлення пристрою та сутностей в MQTT брокері Home Assistant.

Приклад публікації MQTT повідомлення в JSON форматі:

sensor:
  - platform: bme280
	temperature:
  	  name: "OutsideTemp"
  	  id: outside_temp
  	  oversampling: 16x
  	  on_value:
    	    - mqtt.publish_json:
        	  topic: "temperature"
        	  payload: |-
          	    root["OutsideTemp"] = id(outside_temp).state;

Де id — ідентифікатор. Довільна назва малими буквами латинкою, з нижнім підкресленням замість пробілу.
mqtt.publish_json: дозволяє публікувати MQTT повідомлення у JSON форматі (ключ — дані).
topic: публікує дані в існуючу тему, або створює нову.
payload: |- означає початок повідомлення.

Автоматизації ESPHome

Автоматизації — дуже потужний інструмент ESPHome. Автоматизації дозволяють виконувати дію за настання певної умови. Працюють як з Home Assistant, так і незалежно.

Наприклад, ця автоматизація дозволить увімкнути осушувач, коли натиснута кнопка, що приєднана до іншого піна цієї плати.

switch:
  - platform: gpio
    pin: GPIO3
    name: "Living Room Dehumidifier"
    id: dehumidifier1

binary_sensor:
  - platform: gpio
    pin: GPIO4
    name: "Living Room Dehumidifier Toggle Button"
    on_press:
      then:
        - switch.toggle: dehumidifier1

on_press — тригер, що спрацьовує коли натискається кнопка. Тригерів існує дуже багато, таких як: схід сонця, час, увімкнення/ вимкнення перемикача, клік, подвійний клік, після завантаження та перед вимкненням плати та інші.

then — після рядка then починається блок дій. У блоці можна вказати одну або декілька дій. Кожна дія відокремлюється тире. Дій також дуже багато: затримка, публікація MQTT, увімкнути, вимкнути лампу, вентилятор, повернути сервопривід або кроковий двигун, увійти в режим сну та інші.

# ...
on_press:
  then:
    - switch.toggle: dehumidifier1
    - delay: 2s
    - switch.toggle: dehumidifier1

Ця автоматизація дозволяє увімкнути або вимкнути осушувач, зачекати 2 секунди та повернути його до попереднього стану.

Ця автоматизація дозволяє увімкнути осушувач при досягненні 65° та вимкне при 50°:

sensor:
  - platform: dht
    humidity:
      name: "Living Room Humidity"
      on_value_range:
        - above: 65.0
          then:
            - switch.turn_on: dehumidifier1
        - below: 50.0
          then:
            - switch.turn_off: dehumidifier1
    temperature:
      name: "Living Room Temperature"

Цікаві проєкти

З приводу макетування усіх проєктів можна:

• використовувати паяння та макетні плати;
• замовити друковані PCB плати в Китаї та допаяти самостійно (вартість можна розрахувати в калькуляторі на сайті. Для невеликих плат ціна приблизно $5);
  обійтись без паяння і використовувати Dupont дроти для макетування та гарячий клей або breadboard.

Мультисенсор
Керування ролетами
Рахунок імпульсів лічильника
Перемикання музики за допомогою NFC тегів
Віддалене відкриття дверей гаража
Система крапельного поливу
Погодна станція (проєктів погодної станції величезна кількість)
Датчик якості повітря
Відстеження стану пральної машинки
Колонка

Більше цікавих проєктів дивіться на ESPHome у розділі DIY Examples, Форумі Home Assistant у категорії Share your project, тег esphome, на Instructables, Hackday чи Hackster.

Підтримувані плати та апаратні можливості

Усі описані сімейства плат випускаються багатьма компаніями. Через це існує велике різноманіття плат. В залежності від технічних характеристик плати, ESPHome може підтримувати такі апаратні можливості як: шини I2C, SPI, UART і CAN. Підтримуються такі протоколи зв’язку як Wi-Fi MQTT, Modbus, Bluetooth та BLE.

ESPHome підтримує усі плати ESP8266 та ESP32. Нижче наведені лише декілька популярних прикладів.

ESP8266 — це сімейство мікроконтролерів, китайської компанії Espressif з інтерфейсом Wi-Fi, що може виконувати користувацькі програми (в тому числі Arduino IDE) та має інструмент AT команд. Ця плата має зручний формфактор та велику кількість контактів. Я вважаю, що це одна з найкращих плат для початківців.

ESP-01 — найдешевша, і через це найпродаваніша плата Espressif. Не дуже зручна для початківців через відсутність USB. Проте можна використовувати USB TTL конвертер.

NodeMCU — одна з самих популярних плат. Чудово підходить для початківців, має багато контактів та багато посібників в інтернеті.

WeMos D1 Mini — одна з найменших плат розробки для модуля ESP8266.

ESP32 — сімейство двоядерних плат, потужніших та з більшою кількістю пам’яті ніж ESP8266, швидшим Wi-Fi, підтримується Bluetooth та BLE та має більшу кількість GPIO.

NodeMcu ESP32-WROOM-32S та 32D — популярні плати на Aliexpress, що часто використовуються в проєктах домашньої автоматизації. За формфактором дуже схожа на ESP8266 NodeMCU.

ESP32 також представлені в форматі міні. Наприклад, Wemos ESP32 S2 mini.
Цікавою для мене також є плата Wemos ESP32 C3 Pico та інші модифікації ESP C3, своїми мініатюрними розмірами і портом jst для підключення батарейки.

Я назвав найпопулярніші варіанти, проте є і багато інших плат зі своїми унікальними технічними характеристиками. Про ESP32 цікаво розповів блогер Андреас Шпісс у відео, наприклад, тут. А також у дуже інформативній таблиці. Обожнюю його.

RP2040 контролер розроблений компанією Raspberry Fondation. На основі цього мікроконтролера створені плати Raspberry Pi Pico та Pi Pico W. Остання має на борту Wi-Fi 2,4 ГГц та підтримується ESPHome.

Живлення

Живлення через USB. Зазвичай ESP живлять через кабель micro usb. Це забезпечує живлення 5В, а вбудований в плату регулятор захищає плату від перенавантажень. Можна живити плату будь-яким зручним способом: від блоку живлення 5 В, або Power Bank.

Живлення через контакт Vin + GND. Іншим способом живлення ESP32 є використання контакту Vin або широко відомого як контакт 5В. Цей контакт також підключений до вбудованого регулятора напруги та знижує поданий струм в 3.3В. Можна подавати напругу від 5 до 12В, однак рекомендовано не використовувати більше 6-7В, оскільки для роботи ESP32 потрібно лише 3,3В.

Контакт Vin також зручно використовувати із зовнішніми батареями та акумуляторами.

Для живлення можна використовувати:

• літієві батареї;
• літій-полімерні (LiPo) акумулятори;
• літій-іоні (LiIon) акумумулятори;
• нікель металогідридні (ni-mh) батареї;
• LiFePO4 акумулятори.

Живлення через контакт 3.3 В + GND. Контакти 3,3В працює без регулятора напруги. Ні в якому разі не перевищуйте цю напругу інакше є ризик пошкодити плату. Обов’язково з’єднайте GND ESP із GND зовнішнього джерела живлення.

Живлення через JST конектор. Деякі плати, такі як ESP32 C3 pico мають JST конектор для підключення зовнішніх акумуляторів (часто на 3.7 В).

Детальніше у відео про живлення ESP Андреаса Шпісса тут, тут і тут.

Як почати

Щоб почати роботу з ESPHome:

1. Оберіть проєкт, що вас цікавить.
2. Купіть, або знайдіть необхідні плати, датчики та сенсори. За необхідності дроти Dupont (мама-мама, тато-мама), макетну плату, паяльник, припой, каніфоль.
3. Встановіть ESPHome.
4. Завантажте на плату початкову прошивку.
5. Змініть файл конфігурації та завантажте його кабелем або бездротово.
6. Якщо отримуєте помилки в процесі компіляції. Спробуйте перезавантажити Home Assistant або комп’ютер, де встановлено ESPHome, перевірте наявність оновлень. Якщо проблема залишилась, скопіюйте помилку та знайдіть інформацію про неї в інтернеті.

Якщо цей невеликий гайд був вам корисний, подякуйте донатом у фонд «Повернись живим».

Підписуйтеся на Telegram-канал «DOU #tech», щоб не пропустити нові технічні статті