← - Lambda Reference | Contenido | Siguiente: FAQ y solución de problemas →
Integración ESPHome — Home Assistant, Solución de problemas, Próximos pasos
Integración con Home Assistant, solución de problemas y planes de desarrollo.
Contenido
5.1 Integración con Home Assistant
Descubrimiento automático
Tras flashear el ESP32, el dispositivo aparece automáticamente en Home Assistant.
Verificación:
- Configuración -> Dispositivos y servicios
- Find the "New devices discovered" notification
- O bien: ESPHome -> seleccionar el dispositivo
Entidades en Home Assistant
Al usar el ejemplo estándar, se crean las siguientes entidades:
| Entidad | Tipo | Descripción |
|---|---|---|
light.dimmerlink_light |
Light | Dimmer principal |
sensor.dimmerlink_ac_frequency |
Sensor | Frecuencia de red (50/60 Hz) |
sensor.dimmerlink_level |
Sensor | Nivel actual (%) |
select.dimmerlink_curve |
Select | Curva de atenuación |
binary_sensor.dimmerlink_ready |
Binary Sensor | Estado de disponibilidad |
button.dimmerlink_restart_esp |
Button | Reinicio del ESP |
Tarjetas Lovelace
Tarjeta simple
type: light
entity: light.dimmerlink_light
name: Living Room
Tarjeta extendida
type: vertical-stack
cards:
- type: light
entity: light.dimmerlink_light
name: Dimmer
- type: entities
entities:
- entity: select.dimmerlink_curve
name: Curve
- entity: sensor.dimmerlink_ac_frequency
name: Mains Frequency
- entity: binary_sensor.dimmerlink_ready
name: Status
Tarjeta con control deslizante (custom:slider-entity-row)
type: entities
entities:
- entity: light.dimmerlink_light
type: custom:slider-entity-row
name: Brightness
toggle: true
Automatizaciones
Encendido por sensor de movimiento
automation:
- alias: "Light on Motion"
trigger:
- platform: state
entity_id: binary_sensor.motion_sensor
to: "on"
condition:
- condition: sun
after: sunset
action:
- service: light.turn_on
target:
entity_id: light.dimmerlink_light
data:
brightness_pct: 70
transition: 2
Apagado tras 5 minutos
automation:
- alias: "Auto Turn Off"
trigger:
- platform: state
entity_id: binary_sensor.motion_sensor
to: "off"
for:
minutes: 5
action:
- service: light.turn_off
target:
entity_id: light.dimmerlink_light
data:
transition: 5
Modo nocturno (luz tenue)
automation:
- alias: "Night Mode"
trigger:
- platform: time
at: "23:00:00"
condition:
- condition: state
entity_id: light.dimmerlink_light
state: "on"
action:
- service: light.turn_on
target:
entity_id: light.dimmerlink_light
data:
brightness_pct: 20
transition: 10
Cambiar curva según el tipo de carga
automation:
- alias: "Curve for LED"
trigger:
- platform: state
entity_id: input_select.lamp_type
to: "LED"
action:
- service: select.select_option
target:
entity_id: select.dimmerlink_curve
data:
option: "LOG"
- alias: "Curve for Incandescent"
trigger:
- platform: state
entity_id: input_select.lamp_type
to: "Incandescent"
action:
- service: select.select_option
target:
entity_id: select.dimmerlink_curve
data:
option: "RMS"
Scripts
Encendido gradual matutino
script:
morning_light:
alias: "Morning Light"
sequence:
- service: light.turn_on
target:
entity_id: light.dimmerlink_light
data:
brightness_pct: 10
- delay:
seconds: 30
- service: light.turn_on
target:
entity_id: light.dimmerlink_light
data:
brightness_pct: 50
transition: 120 # 2 minutes
Simulación de presencia
script:
presence_simulation:
alias: "Presence Simulation"
sequence:
- repeat:
count: 10
sequence:
- service: light.turn_on
target:
entity_id: light.dimmerlink_light
data:
brightness_pct: "{{ range(30, 80) | random }}"
- delay:
minutes: "{{ range(5, 20) | random }}"
- service: light.turn_off
target:
entity_id: light.dimmerlink_light
- delay:
minutes: "{{ range(10, 30) | random }}"
Escenas
scene:
- name: "Movie"
entities:
light.dimmerlink_light:
state: on
brightness_pct: 15
- name: "Reading"
entities:
light.dimmerlink_light:
state: on
brightness_pct: 80
- name: "Romantic"
entities:
light.dimmerlink_light:
state: on
brightness_pct: 30
Grupos
light:
- platform: group
name: "All Dimmers"
entities:
- light.dimmerlink_living_room
- light.dimmerlink_bedroom
- light.dimmerlink_kitchen
Sensor de potencia mediante plantilla
Si se conoce la potencia de la lámpara:
sensor:
- platform: template
sensors:
dimmer_power:
friendly_name: "Dimmer Power"
unit_of_measurement: "W"
value_template: >
{% set brightness = state_attr('light.dimmerlink_light', 'brightness') | default(0) %}
{% set max_power = 100 %}
{{ (brightness / 255 * max_power) | round(1) }}
Historial y estadísticas
Añadir a configuration.yaml:
recorder:
include:
entities:
- light.dimmerlink_light
- sensor.dimmerlink_level
- sensor.dimmerlink_ac_frequency
history:
include:
entities:
- light.dimmerlink_light
5.2 Solución de problemas
Problemas de I2C
Dispositivo no encontrado (0x50)
Symptom: Logs don't show "Found i2c device at address 0x50"
Verificación:
| Verificación | Solución |
|---|---|
| ¿DimmerLink en modo I2C? | Cambiar mediante UART: 02 5B |
| ¿Alimentación conectada? | VCC -> 3,3V, GND -> GND |
| ¿Cableado correcto? | SDA -> SDA, SCL -> SCL (¡sin cruzar!) |
| ¿Resistencias pull-up? | Añadir 4,7 kΩ en SDA y SCL hacia 3,3V |
| ¿Cables suficientemente cortos? | I2C funciona hasta 30 cm |
Diagnóstico:
# Add to configuration for debugging
i2c:
sda: GPIO21
scl: GPIO22
scan: true # Enable scanning
id: bus_a
logger:
level: DEBUG
logs:
i2c: DEBUG
Errores I2C intermitentes
Symptom: "I2C communication failed" from time to time
Soluciones:
- Reducir la frecuencia:
yaml
i2c:
frequency: 50kHz # En lugar de 100kHz
- Añadir retardos:
yaml
output:
- platform: template
write_action:
- delay: 1ms # Antes de escribir
- lambda: |-
// ... código
- Verificar la fuente de alimentación — una alimentación inestable provoca errores I2C
Problemas de WiFi
ESP32 Doesn't Connect to WiFi
Verificación:
- SSID y contraseña correctos en
secrets.yaml - WiFi on 2.4 GHz (ESP32 doesn't support 5 GHz)
- El router no bloquea nuevos dispositivos
Solución — AP de reserva:
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
ap:
ssid: "dimmerlink-fallback"
password: "12345678"
captive_portal:
If it doesn't connect to WiFi — it will create an access point for configuration.
Desconexiones frecuentes
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
fast_connect: true
power_save_mode: NONE # Disable power saving
Problemas con Home Assistant
Device Doesn't Appear in HA
- Verificar que el complemento ESPHome está en ejecución
- Comprobar la api key en la configuración
- Reiniciar Home Assistant
- Añadir manualmente: Configuración -> Integraciones -> Añadir -> ESPHome
"Entity unavailable"
Causes:
- ESP32 offline
- WiFi issues
- API key mismatch
Verificación:
ping dimmerlink.local
Problemas de atenuación
La lámpara parpadea
Causas y soluciones:
| Causa | Solución |
|---|---|
| LED no regulable | Use lamps marked "dimmable" |
| Carga demasiado baja | Mínimo 10–25 W para funcionamiento estable |
| Curva incorrecta | Probar LOG para LED |
| Interferencias en la red | Añadir un snubber RC a la salida del dimmer |
Lamp Doesn't Turn Off Completely
DimmerLink desactiva completamente el TRIAC con level=0. Si la lámpara sigue brillando:
- Problema en el dimmer o el cableado
- Algunos drivers LED tienen corriente de fuga
Rango de brillo demasiado estrecho
Probar otras curvas:
# In Home Assistant Developer Tools
service: select.select_option
target:
entity_id: select.dimmerlink_curve
data:
option: "RMS" # or "LOG"
Problemas con ESPHome
Error de compilación
«lambda function not allowed»
Verificar la indentación en YAML — lambda debe tener la indentación correcta:
# Correct
write_action:
- lambda: |-
uint8_t data[2] = {0x10, 50};
id(bus_a).write(0x50, data, 2, true);
# Incorrect (missing "|-")
write_action:
- lambda:
uint8_t data[2] = {0x10, 50};
«id not found»
Asegurarse de que id: bus_a esté declarado en la sección i2c:.
OTA no funciona
- Verificar que el ESP32 está en la misma red
- Usar la IP en lugar del nombre de host:
bash
esphome run dimmerlink.yaml --device 192.168.1.100
Comandos de diagnóstico
Comprobación I2C desde ESPHome
Añadir un botón de diagnóstico:
button:
- platform: template
name: "I2C Diagnostic"
on_press:
- lambda: |-
ESP_LOGI("diag", "=== I2C Diagnostic ===");
// Check connection
uint8_t reg = 0x00;
uint8_t status = 0;
auto err = id(bus_a).write(0x50, ®, 1, false);
ESP_LOGI("diag", "Write result: %d", err);
err = id(bus_a).read(0x50, &status, 1);
ESP_LOGI("diag", "Read result: %d, status: 0x%02X", err, status);
// Read version
reg = 0x03;
uint8_t version = 0;
id(bus_a).write(0x50, ®, 1, false);
id(bus_a).read(0x50, &version, 1);
ESP_LOGI("diag", "Firmware: %d", version);
// Read frequency
reg = 0x20;
uint8_t freq = 0;
id(bus_a).write(0x50, ®, 1, false);
id(bus_a).read(0x50, &freq, 1);
ESP_LOGI("diag", "AC Frequency: %d Hz", freq);
ESP_LOGI("diag", "=== Done ===");
Registro de todas las operaciones
logger:
level: DEBUG
logs:
i2c: DEBUG
api: DEBUG
sensor: DEBUG
Restablecimiento de fábrica
ESP32
- Borrar la memoria flash:
bash
esptool.py --port COM3 erase_flash
- Volver a flashear el firmware
DimmerLink
Enviar el comando RESET:
button:
- platform: template
name: "Factory Reset DimmerLink"
on_press:
- lambda: |-
uint8_t data[2] = {0x01, 0x01};
id(bus_a).write(0x50, data, 2, true);
- delay: 3s
Tabla de códigos de error
| Código | Nombre | Causa | Solución |
|---|---|---|---|
| 0x00 | OK | — | — |
| 0xF9 | ERR_SYNTAX | Registro inválido | Verificar la dirección del registro |
| 0xFC | ERR_NOT_READY | No calibrado o error FLASH | Esperar 2 seg tras encender |
| 0xFD | ERR_INDEX | Índice de dimmer inválido | Usar 0 |
| 0xFE | ERR_PARAM | Parámetro inválido | level <= 100, curve <= 2 |
5.3 Próximos pasos
Estado actual
DimmerLink v1.0:
- I2C interface
- UART interface
- Basic dimming (0-100%)
- Three curves (LINEAR, RMS, LOG)
- Auto-detection of mains frequency
- I2C address change
ESPHome Integration v1.0:
- Light entity
- All sensors
- Curve selection
- Diagnostics
- Multi-device
Planes de desarrollo
DimmerLink v2.0 (en desarrollo)
| Función | Estado | Descripción |
|---|---|---|
| Protección térmica | En desarrollo | Monitoreo NTC, ventilador PWM |
| FADE progresivo | En desarrollo | Fundido por hardware a través de comando |
| Multi-canal | Planificado | Hasta 4 canales en un módulo |
| Configuración EEPROM | Planificado | Guardar nivel y curva |
Integración ESPHome v2.0
| Función | Estado | Descripción |
|---|---|---|
| Componente nativo | Disponible | External Component |
| Monitoreo de temperatura | En desarrollo | Sensor de temperatura |
| Control del ventilador | En desarrollo | Gestión de refrigeración |
| Monitoreo de energía | Planificado | Integración con ACS712/CT |
Componente nativo ESPHome
Ya está disponible un componente externo nativo de ESPHome. Proporciona una configuración YAML limpia sin código lambda:
external_components:
- source: github://robotdyn-dimmer/DimmerLink@main
components: [dimmerlink]
dimmerlink:
id: dimmer1
address: 0x50
light:
- platform: dimmerlink
dimmerlink_id: dimmer1
name: "Light"
sensor:
- platform: dimmerlink
dimmerlink_id: dimmer1
ac_frequency:
name: "AC Frequency"
Proyectos avanzados
Enrutador solar
Usar DimmerLink para enrutar el exceso de energía solar:
+---------------+ +---------------+ +---------------+
| Solar Panel |---->| CT Sensor |---->| ESP32 |
+---------------+ +---------------+ | + ESPHome |
| |
+---------------+ +---------------+ | |
| Heater |<----| DimmerLink |<----| |
+---------------+ +---------------+ +---------------+
Sistema multihabitación
# Central controller for the whole house
substitutions:
# Dimmer addresses
living_room: "0x50"
bedroom: "0x51"
kitchen: "0x52"
bathroom: "0x53"
# 4 dimmers on one ESP32
Despertador inteligente
# Gradual light turn on for waking up
automation:
- alias: "Sunrise Alarm"
trigger:
- platform: time
at: "07:00:00"
action:
- service: light.turn_on
target:
entity_id: light.bedroom_dimmer
data:
brightness_pct: 1
- repeat:
count: 30
sequence:
- delay: 60
- service: light.turn_on
target:
entity_id: light.bedroom_dimmer
data:
brightness_pct: "{{ repeat.index * 3 }}"
transition: 60
Comentarios
¿Encontró un error o tiene una sugerencia?
- GitHub Issues: DimmerLink Repository
- Documentación: rbdimmer.com/docs
¿Quiere contribuir al desarrollo?
- Probar nuevas versiones
- Documentación y traducciones
- Ejemplos de uso
Enlaces útiles
| Recurso | Enlace |
|---|---|
| Documentación DimmerLink | rbdimmer.com/docs |
| ESPHome | esphome.io |
| Home Assistant | home-assistant.io |
| ESPHome I2C | esphome.io/components/i2c |
| ESPHome Light | esphome.io/components/light |
| HACS | hacs.xyz |
Historial de cambios
| Versión | Fecha | Cambios |
|---|---|---|
| 1.0 | 2026-02 | Versión inicial |
← - Lambda Reference | Contenido | Siguiente: FAQ y solución de problemas →