← - Lambda-интеграция | Содержание | Далее: - Lambda-сущности →

Интеграция с ESPHome — Введение

Интеграция DimmerLink с Home Assistant через ESPHome.

Содержание

Дополнительные разделы:

Справочник Lambda — справочник по I2C и регистрам
Готовые сущности — готовые блоки кода для копирования
Полные примеры — рабочие конфигурации

1. Обзор

Что такое ESPHome?

ESPHome — это система для создания прошивок ESP8266/ESP32 с помощью простых YAML-конфигураций. Устройства ESPHome автоматически интегрируются с Home Assistant.

Зачем ESPHome + DimmerLink?

text

┌─────────────────┐     I2C      ┌─────────────┐     WiFi     ┌─────────────────┐
│   DimmerLink    │◄────────────►│    ESP32    │◄────────────►│  Home Assistant │
│  (AC Dimmer)    │              │  (ESPHome)  │              │                 │
└─────────────────┘              └─────────────┘              └─────────────────┘

Преимущества:

Возможность	Описание
Интеграция с HA	Диммер отображается как сущность Light
Автоматизация	Использование в сценариях Home Assistant
OTA-обновления	Беспроводное обновление прошивки
Локальное управление	Работает без интернета
Низкая задержка	Прямое подключение, без облака

Архитектура решения

text

Home Assistant
      │
      │ WiFi (Native API)
      ▼
   ESP32 + ESPHome
      │
      │ I2C (100 kHz)
      ▼
  DimmerLink
      │
      │ Zero-Cross + Gate
      ▼
   AC Dimmer
      │
      │ AC 110/220V
      ▼
    Lamp

Подход к интеграции

DimmerLink не имеет готового компонента в ESPHome. Мы используем lambda-функции — встроенный C++ код в YAML-конфигурации.

Почему lambda?

Не требуются внешние библиотеки
Полный контроль над I2C-коммуникацией
Работает с любой версией ESPHome
Легко адаптировать под новые регистры

Как это выглядит:

yaml

output:
  - platform: template
    id: dimmerlink_output
    type: float
    write_action:
      - lambda: |-
          uint8_t level = (uint8_t)(state * 100.0f);
          uint8_t data[2] = {0x10, level};
          id(bus_a).write(0x50, data, 2, true);

2. Требования

Аппаратные требования

Компонент	Требование	Примечание
DimmerLink	v1.0+	В режиме I2C
ESP32	Любой вариант	ESP32, ESP32-C3, ESP32-S2, ESP32-S3
AC-диммер	Модуль на TRIAC	С входами Z-C и DIM
Нагрузка	Диммируемая	Лампы накаливания, LED (диммируемые)

Поддерживаемые платы ESP32

Плата	I2C по умолчанию	Примечание
ESP32 DevKit	GPIO21/GPIO22	Рекомендуется
ESP32-C3	GPIO8/GPIO9	Компактная
ESP32-S2	GPIO8/GPIO9	Встроенный USB
ESP32-S3	GPIO8/GPIO9	Двухъядерная
ESP32-WROOM	GPIO21/GPIO22	Классическая
NodeMCU-32S	GPIO21/GPIO22	С USB

Warning

**ESP8266** тоже поддерживается, но для стабильной работы I2C рекомендуется ESP32.

Программные требования

Компонент	Версия	Где получить
ESPHome	2023.1+	Дополнение Home Assistant или CLI
Home Assistant	2023.1+	home-assistant.io
Python	3.9+	Только для ESPHome CLI

Проверка версии ESPHome

In Home Assistant:
Settings → Add-ons → ESPHome → Info

CLI:

bash

esphome version

Перед началом работы

☐ DimmerLink переключён в режим I2C (UART-команда: `02 5B`)

☐ Плата ESP32 в наличии

☐ ESPHome установлен

☐ Доступна сеть WiFi

☐ Home Assistant запущен (необязательно)

3. Подключение

Схема подключения

text

┌─────────────┐         ┌─────────────────┐         ┌─────────────┐
│   ESP32     │         │   DimmerLink    │         │  AC Dimmer  │
│             │         │                 │         │             │
│  3.3V ──────┼────────►│ VCC             │         │             │
│  GND ───────┼────────►│ GND         VCC ├────────►│ VCC         │
│  GPIO21 ────┼────────►│ SDA         GND ├────────►│ GND         │
│  GPIO22 ────┼────────►│ SCL         Z-C ├────────►│ Z-C         │
│             │         │             DIM ├────────►│ DIM         │
└─────────────┘         └─────────────────┘         └─────────────┘

Таблица подключения

ESP32	DimmerLink	Функция
3.3V	VCC	Питание
GND	GND	Земля
GPIO21	SDA	I2C Data
GPIO22	SCL	I2C Clock

DimmerLink	AC-диммер	Функция
VCC	VCC	Питание
GND	GND	Земля
Z-C	Z-C	Переход через ноль
DIM	DIM	Gate

Подтягивающие резисторы

ESP32 имеет встроенные подтягивающие резисторы, но для надёжной работы рекомендуются внешние:

Длина провода	Резисторы
< 10 см	Может работать без внешних
10–30 см	Рекомендуется 4,7 кОм
> 30 см	Требуется 2,2–4,7 кОм

Переключение DimmerLink в режим I2C

DimmerLink поставляется в режиме UART. Для работы с ESPHome требуется I2C.

Через UART (до подключения к ESP32):

python

import serial
ser = serial.Serial('COM3', 115200)
ser.write(bytes([0x02, 0x5B]))  # SWITCH_I2C
# Response: 0x00 = OK

Или через терминал (HEX-режим):

text

Send: 02 5B
Response: 00

После переключения DimmerLink сохраняет режим в EEPROM.

Проверка подключения

После подключения и прошивки ESP32 в логах должно появиться:

text

[I][i2c.arduino:XX]: Found i2c device at address 0x50

Info

**Подробная документация по подключению:** [Подключение оборудования](https://www.rbdimmer.com/docs/dimmerlink-HardwareConnection)

4. Базовая конфигурация

Шаг 1: Создание проекта

В Home Assistant (дополнение):

Settings → Add-ons → ESPHome
"+ NEW DEVICE"
Имя: dimmerlink
Выберите тип платы: ESP32

CLI:

bash

esphome wizard dimmerlink.yaml

Шаг 2: Базовый YAML

Создайте файл dimmerlink.yaml:

yaml

# ============================================================
# DimmerLink + ESPHome — Basic Configuration
# ============================================================

substitutions:
  device_name: "dimmerlink"
  friendly_name: "DimmerLink"

esphome:
  name: ${device_name}
  friendly_name: ${friendly_name}

esp32:
  board: esp32dev
  framework:
    type: arduino

# Logging
logger:
  level: INFO

# Home Assistant API
api:
  encryption:
    key: !secret api_key

# OTA updates
ota:
  platform: esphome
  password: !secret ota_password

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

  # Fallback access point
  ap:
    ssid: "${device_name}-AP"
    password: "12345678"

captive_portal:

# ============================================================
# I2C Bus
# ============================================================
i2c:
  sda: GPIO21
  scl: GPIO22
  scan: true
  frequency: 100kHz
  id: bus_a

# ============================================================
# Output — Communication with DimmerLink
# ============================================================
output:
  - platform: template
    id: dimmerlink_output
    type: float
    write_action:
      - lambda: |-
          // Convert 0.0-1.0 → 0-100%
          uint8_t level = (uint8_t)(state * 100.0f);
          if (level > 100) level = 100;

          // Write to DIM0_LEVEL register (0x10)
          uint8_t data[2] = {0x10, level};
          id(bus_a).write(0x50, data, 2, true);

# ============================================================
# Light — What Home Assistant sees
# ============================================================
light:
  - platform: monochromatic
    name: "Light"
    output: dimmerlink_output
    default_transition_length: 1s
    gamma_correct: 1.0
    restore_mode: RESTORE_DEFAULT_OFF

Шаг 3: Файл secrets.yaml

Создайте secrets.yaml в той же папке:

yaml

wifi_ssid: "YourNetwork"
wifi_password: "YourPassword"
api_key: "generate_via_esphome"
ota_password: "your_ota_password"

Tip

**Генерация api_key:** ESPHome автоматически генерирует ключ при создании проекта. Или используйте: `esphome wizard`.

Шаг 4: Компиляция и загрузка

В Home Assistant:

Click "INSTALL" on the device card
Select "Plug into this computer" (first time via USB)
Дождитесь завершения загрузки

CLI:

bash

# First upload via USB
esphome run dimmerlink.yaml

# Subsequent updates — over the air
esphome run dimmerlink.yaml --device dimmerlink.local

Шаг 5: Проверка

В логах ESPHome:

text

[I][i2c.arduino:XX]: Found i2c device at address 0x50
[I][app:XX]: ESPHome version 2024.x.x compiled on ...
[I][wifi:XX]: WiFi Connected!
[I][api:XX]: Home Assistant connected!

В Home Assistant:

Settings → Devices & Services
Find "ESPHome" → "DimmerLink"
Должна появиться сущность Light

Шаг 6: Тестирование

В Home Assistant:

Откройте карточку Light
Переместите ползунок яркости
Лампа должна изменить яркость

Через Developer Tools:

yaml

service: light.turn_on
target:
  entity_id: light.dimmerlink_light
data:
  brightness_pct: 50

What's Next?

Расширение функциональности

После успешной базовой конфигурации добавьте:

Возможность	Раздел
Выбор кривой диммирования	Готовые сущности → Select
Мониторинг частоты AC	Готовые сущности → Sensor
Физическая кнопка	Примеры → С кнопкой
Несколько диммеров	Примеры → Мультиустройство

Справочные материалы

Документ	Содержимое
Справочник Lambda	Все регистры, коды команд, примеры lambda
Готовые сущности	Готовые блоки кода для каждого типа сущностей
Полные примеры	6 готовых конфигураций

Быстрый старт (TL;DR)

yaml

# Minimum for operation — copy and modify WiFi

substitutions:
  device_name: "dimmerlink"

esphome:
  name: ${device_name}

esp32:
  board: esp32dev

logger:
api:
ota:

wifi:
  ssid: "YOUR_WIFI"
  password: "YOUR_PASSWORD"

i2c:
  sda: GPIO21
  scl: GPIO22
  id: bus_a

output:
  - platform: template
    id: dimmer_out
    type: float
    write_action:
      - lambda: |-
          uint8_t level = (uint8_t)(state * 100.0f);
          uint8_t data[2] = {0x10, level};
          id(bus_a).write(0x50, data, 2, true);

light:
  - platform: monochromatic
    name: "Dimmer"
    output: dimmer_out
    gamma_correct: 1.0

30 строк — и диммер в Home Assistant!

История версий

Версия	Дата	Изменения
1.0	2026-02	Первый выпуск

← - Lambda-интеграция | Содержание | Далее: - Lambda-сущности →

Продукты

Рекомендуемые

Начать

Интеграции

Руководства и статьи

ACRouter

Презентация проекта

Начало работы

Интеграции

AC Диммеры

DimmerLink

ACRouter

GitHub

Интеграция с ESPHome — Введение

Содержание

1. Обзор

Что такое ESPHome?

Зачем ESPHome + DimmerLink?

Архитектура решения

Подход к интеграции

2. Требования

Аппаратные требования

Поддерживаемые платы ESP32

Программные требования

Проверка версии ESPHome

Перед началом работы

3. Подключение

Схема подключения

Таблица подключения

Подтягивающие резисторы

Переключение DimmerLink в режим I2C

Проверка подключения

4. Базовая конфигурация

Шаг 1: Создание проекта

Шаг 2: Базовый YAML

Шаг 3: Файл secrets.yaml

Шаг 4: Компиляция и загрузка

Шаг 5: Проверка

Шаг 6: Тестирование

What's Next?

Расширение функциональности

Рекомендуемая конфигурация

Справочные материалы

Быстрый старт (TL;DR)

История версий