← - Integración Lambda | Contenido | Siguiente: - Entidades Lambda →

Integración con ESPHome — Introducción

Integración de DimmerLink con Home Assistant a través de ESPHome.

Contenido

Secciones adicionales:

Referencia Lambda — referencia de I2C y registros
Entidades listas — bloques de código para copiar y pegar
Ejemplos completos — configuraciones funcionales

1. Descripción general

¿Qué es ESPHome?

ESPHome es un sistema para crear firmware de ESP8266/ESP32 mediante configuraciones YAML sencillas. Los dispositivos ESPHome se integran automáticamente con Home Assistant.

¿Por qué ESPHome + DimmerLink?

text

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

Ventajas:

Característica	Descripción
Integración con HA	El dimmer aparece como entidad Light
Automatización	Uso en escenarios de Home Assistant
Actualizaciones OTA	Actualizaciones de firmware inalámbricas
Control local	Funciona sin Internet
Baja latencia	Conexión directa, sin nube

Arquitectura de la solución

text

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

Enfoque de integración

DimmerLink no tiene un componente predefinido en ESPHome. Utilizamos funciones lambda — código C++ integrado en la configuración YAML.

¿Por qué lambda?

No se requieren bibliotecas externas
Control total sobre la comunicación I2C
Compatible con cualquier versión de ESPHome
Fácil de adaptar para nuevos registros

Así se ve:

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. Requisitos

Requisitos de hardware

Componente	Requisito	Nota
DimmerLink	v1.0+	En modo I2C
ESP32	Cualquier variante	ESP32, ESP32-C3, ESP32-S2, ESP32-S3
Dimmer AC	Módulo TRIAC	Con entradas Z-C y DIM
Carga	Regulable	Bombillas incandescentes, LED (regulables)

Placas ESP32 compatibles

Placa	I2C por defecto	Nota
ESP32 DevKit	GPIO21/GPIO22	Recomendada
ESP32-C3	GPIO8/GPIO9	Compacta
ESP32-S2	GPIO8/GPIO9	USB nativo
ESP32-S3	GPIO8/GPIO9	Doble núcleo
ESP32-WROOM	GPIO21/GPIO22	Clásica
NodeMCU-32S	GPIO21/GPIO22	Con USB

Warning

**ESP8266** también es compatible, pero se recomienda ESP32 para un funcionamiento I2C estable.

Requisitos de software

Componente	Versión	Dónde obtenerlo
ESPHome	2023.1+	Add-on de Home Assistant o CLI
Home Assistant	2023.1+	home-assistant.io
Python	3.9+	Solo para ESPHome CLI

Verificar la versión de ESPHome

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

CLI:

bash

esphome version

Antes de comenzar

☐ DimmerLink cambiado a modo I2C (comando UART: `02 5B`)

☐ Placa ESP32 disponible

☐ ESPHome instalado

☐ Red WiFi disponible

☐ Home Assistant en ejecución (opcional)

3. Conexión

Diagrama de cableado

text

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

Tabla de conexión

ESP32	DimmerLink	Función
3.3V	VCC	Alimentación
GND	GND	Tierra
GPIO21	SDA	I2C Data
GPIO22	SCL	I2C Clock

DimmerLink	Dimmer AC	Función
VCC	VCC	Alimentación
GND	GND	Tierra
Z-C	Z-C	Cruce por cero
DIM	DIM	Gate

Resistencias pull-up

ESP32 cuenta con pull-ups internos, pero se recomiendan resistencias externas para un funcionamiento fiable:

Longitud del cable	Resistencias
< 10 cm	Puede funcionar sin externas
10–30 cm	4,7 kΩ recomendado
> 30 cm	2,2–4,7 kΩ requerido

Cambiar DimmerLink a modo I2C

DimmerLink se envía en modo UART. Se requiere I2C para ESPHome.

Vía UART (antes de conectar al ESP32):

python

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

O vía terminal (modo HEX):

text

Send: 02 5B
Response: 00

Después del cambio, DimmerLink guarda el modo en la EEPROM.

Verificar la conexión

Después de conectar y flashear el ESP32, los logs deben mostrar:

text

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

Info

**Documentación detallada de conexión:** [Conexión de hardware](https://www.rbdimmer.com/docs/dimmerlink-HardwareConnection)

4. Configuración básica

Paso 1: Crear proyecto

En Home Assistant (Add-on):

Settings → Add-ons → ESPHome
"+ NEW DEVICE"
Nombre: dimmerlink
Seleccionar tipo de placa: ESP32

CLI:

bash

esphome wizard dimmerlink.yaml

Paso 2: YAML básico

Cree el archivo 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

Paso 3: Archivo secrets.yaml

Cree secrets.yaml en la misma carpeta:

yaml

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

Tip

**Generar api_key:** ESPHome genera automáticamente una clave al crear un proyecto. O utilice: `esphome wizard`.

Paso 4: Compilar y cargar

En Home Assistant:

Click "INSTALL" on the device card
Select "Plug into this computer" (first time via USB)
Espere a que se complete la carga

CLI:

bash

# First upload via USB
esphome run dimmerlink.yaml

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

Paso 5: Verificación

En los logs de 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!

En Home Assistant:

Settings → Devices & Services
Find "ESPHome" → "DimmerLink"
Debe aparecer una entidad Light

Paso 6: Prueba

En Home Assistant:

Abra la tarjeta Light
Mueva el control deslizante de brillo
La lámpara debe cambiar de brillo

Vía Developer Tools:

yaml

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

What's Next?

Ampliar la funcionalidad

Después de una configuración básica exitosa, añada:

Característica	Sección
Selección de curva de atenuación	Entidades listas → Select
Monitoreo de frecuencia AC	Entidades listas → Sensor
Botón físico	Ejemplos → Con botón
Múltiples dimmers	Ejemplos → Multi-dispositivo

Configuración recomendada

Para la mayoría de los usuarios, recomendamos el ejemplo estándar:

→ 03_examples.md → 7.2 Standard

Incluye:

Luz con transiciones suaves
Selección de curva (LINEAR / RMS / LOG)
Sensor de frecuencia AC
Estado de disponibilidad
Botón de reinicio

Materiales de referencia

Documento	Contenido
Referencia Lambda	Todos los registros, códigos de comando, ejemplos lambda
Entidades listas	Bloques de código para copiar por tipo de entidad
Ejemplos completos	6 configuraciones listas

Inicio rápido (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 líneas — ¡y el dimmer está en Home Assistant!

Historial de versiones

Versión	Fecha	Cambios
1.0	2026-02	Versión inicial

← - Integración Lambda | Contenido | Siguiente: - Entidades Lambda →

Productos

Destacados

Comenzar

Integraciones

Guías y Artículos

ACRouter

Muestra de Proyecto

Comenzando

Integraciones

Atenuadores de CA

DimmerLink

ACRouter

GitHub

Integración con ESPHome — Introducción

Contenido

1. Descripción general

¿Qué es ESPHome?

¿Por qué ESPHome + DimmerLink?

Arquitectura de la solución

Enfoque de integración

2. Requisitos

Requisitos de hardware

Placas ESP32 compatibles

Requisitos de software

Verificar la versión de ESPHome

Antes de comenzar

3. Conexión

Diagrama de cableado

Tabla de conexión

Resistencias pull-up

Cambiar DimmerLink a modo I2C

Verificar la conexión

4. Configuración básica

Paso 1: Crear proyecto

Paso 2: YAML básico

Paso 3: Archivo secrets.yaml

Paso 4: Compilar y cargar

Paso 5: Verificación

Paso 6: Prueba

What's Next?

Ampliar la funcionalidad

Configuración recomendada

Materiales de referencia

Inicio rápido (TL;DR)

Historial de versiones