← - Integrazione Lambda | Indice | Avanti: - Entità Lambda →

Integrazione ESPHome — Introduzione

Integrazione di DimmerLink con Home Assistant tramite ESPHome.

Indice

Sezioni aggiuntive:

Riferimento Lambda — riferimento I2C e registri
Entità pronte — blocchi di codice da copiare e incollare
Esempi completi — configurazioni funzionanti

1. Panoramica

Cos'è ESPHome?

ESPHome è un sistema per creare firmware ESP8266/ESP32 utilizzando semplici configurazioni YAML. I dispositivi ESPHome si integrano automaticamente con Home Assistant.

Perché ESPHome + DimmerLink?

text

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

Vantaggi:

Funzionalità	Descrizione
Integrazione HA	Il dimmer appare come entità Light
Automazione	Utilizzo negli scenari di Home Assistant
Aggiornamenti OTA	Aggiornamenti firmware wireless
Controllo locale	Funziona senza Internet
Bassa latenza	Connessione diretta, senza cloud

Architettura della soluzione

text

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

Approccio all'integrazione

DimmerLink non dispone di un componente predefinito in ESPHome. Utilizziamo le funzioni lambda — codice C++ incorporato nella configurazione YAML.

Perché lambda?

Nessuna libreria esterna necessaria
Controllo completo sulla comunicazione I2C
Compatibile con qualsiasi versione di ESPHome
Facile da adattare per nuovi registri

Ecco come si presenta:

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

Requisiti hardware

Componente	Requisito	Nota
DimmerLink	v1.0+	In modalità I2C
ESP32	Qualsiasi variante	ESP32, ESP32-C3, ESP32-S2, ESP32-S3
Dimmer AC	Modulo TRIAC	Con ingressi Z-C e DIM
Carico	Dimmerabile	Lampadine a incandescenza, LED (dimmerabili)

Schede ESP32 supportate

Scheda	I2C predefinito	Nota
ESP32 DevKit	GPIO21/GPIO22	Consigliata
ESP32-C3	GPIO8/GPIO9	Compatta
ESP32-S2	GPIO8/GPIO9	USB nativo
ESP32-S3	GPIO8/GPIO9	Dual-core
ESP32-WROOM	GPIO21/GPIO22	Classica
NodeMCU-32S	GPIO21/GPIO22	Con USB

Warning

**ESP8266** è supportato, ma ESP32 è consigliato per un funzionamento I2C stabile.

Requisiti software

Componente	Versione	Dove ottenerlo
ESPHome	2023.1+	Add-on Home Assistant o CLI
Home Assistant	2023.1+	home-assistant.io
Python	3.9+	Solo per ESPHome CLI

Verificare la versione di ESPHome

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

CLI:

bash

esphome version

Prima di iniziare

☐ DimmerLink impostato in modalità I2C (comando UART: `02 5B`)

☐ Scheda ESP32 disponibile

☐ ESPHome installato

☐ Rete WiFi disponibile

☐ Home Assistant in esecuzione (opzionale)

3. Collegamento

Schema di cablaggio

text

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

Tabella di collegamento

ESP32	DimmerLink	Funzione
3.3V	VCC	Alimentazione
GND	GND	Massa
GPIO21	SDA	I2C Data
GPIO22	SCL	I2C Clock

DimmerLink	Dimmer AC	Funzione
VCC	VCC	Alimentazione
GND	GND	Massa
Z-C	Z-C	Passaggio per lo zero
DIM	DIM	Gate

Resistenze di pull-up

ESP32 dispone di pull-up interni, ma si raccomandano resistenze esterne per un funzionamento affidabile:

Lunghezza del cavo	Resistenze
< 10 cm	Può funzionare senza esterne
10–30 cm	4,7 kΩ consigliato
> 30 cm	2,2–4,7 kΩ richiesto

Impostare DimmerLink in modalità I2C

DimmerLink viene fornito in modalità UART. La modalità I2C è necessaria per ESPHome.

Via UART (prima del collegamento a ESP32):

python

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

O via terminale (modalità HEX):

text

Send: 02 5B
Response: 00

Dopo il passaggio, DimmerLink salva la modalità nella EEPROM.

Verifica del collegamento

Dopo il collegamento e il flash di ESP32, i log devono mostrare:

text

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

Info

**Documentazione dettagliata sul collegamento:** [Collegamento hardware](https://www.rbdimmer.com/docs/dimmerlink-HardwareConnection)

4. Configurazione di base

Passo 1: Creare il progetto

In Home Assistant (Add-on):

Settings → Add-ons → ESPHome
"+ NEW DEVICE"
Nome: dimmerlink
Selezionare il tipo di scheda: ESP32

CLI:

bash

esphome wizard dimmerlink.yaml

Passo 2: YAML di base

Creare il file 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

Passo 3: File secrets.yaml

Creare secrets.yaml nella stessa cartella:

yaml

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

Tip

**Generazione di api_key:** ESPHome genera automaticamente una chiave durante la creazione del progetto. In alternativa, utilizzare: `esphome wizard`.

Passo 4: Compilare e caricare

In Home Assistant:

Click "INSTALL" on the device card
Select "Plug into this computer" (first time via USB)
Attendere il completamento del caricamento

CLI:

bash

# First upload via USB
esphome run dimmerlink.yaml

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

Passo 5: Verifica

Nei log di 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!

In Home Assistant:

Settings → Devices & Services
Find "ESPHome" → "DimmerLink"
Deve apparire un'entità Light

Passo 6: Test

In Home Assistant:

Aprire la scheda Light
Spostare il cursore della luminosità
La lampada deve cambiare luminosità

Tramite Developer Tools:

yaml

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

What's Next?

Estendere le funzionalità

Dopo una configurazione di base riuscita, aggiungere:

Funzionalità	Sezione
Selezione della curva di dimmerizzazione	Entità pronte → Select
Monitoraggio frequenza AC	Entità pronte → Sensor
Pulsante fisico	Esempi → Con pulsante
Più dimmer	Esempi → Multi-dispositivo

Configurazione consigliata

Per la maggior parte degli utenti, consigliamo l'esempio standard:

→ 03_examples.md → 7.2 Standard

Include:

Luce con transizioni fluide
Selezione curva (LINEAR / RMS / LOG)
Sensore di frequenza AC
Stato di disponibilità
Pulsante di riavvio

Materiali di riferimento

Documento	Contenuto
Riferimento Lambda	Tutti i registri, codici di comando, esempi lambda
Entità pronte	Blocchi di codice da copiare per ogni tipo di entità
Esempi completi	6 configurazioni pronte

Avvio rapido (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 righe — e il dimmer è in Home Assistant!

Cronologia delle versioni

Versione	Data	Modifiche
1.0	2026-02	Prima versione

← - Integrazione Lambda | Indice | Avanti: - Entità Lambda →

Prodotti

In Evidenza

Inizia

Integrazioni

Guide e Articoli

ACRouter

Vetrina Progetti

Iniziare

Integrazioni

Dimmer AC

DimmerLink

ACRouter

GitHub

Integrazione ESPHome — Introduzione

Indice

1. Panoramica

Cos'è ESPHome?

Perché ESPHome + DimmerLink?

Architettura della soluzione

Approccio all'integrazione

2. Requisiti

Requisiti hardware

Schede ESP32 supportate

Requisiti software

Verificare la versione di ESPHome

Prima di iniziare

3. Collegamento

Schema di cablaggio

Tabella di collegamento

Resistenze di pull-up

Impostare DimmerLink in modalità I2C

Verifica del collegamento

4. Configurazione di base

Passo 1: Creare il progetto

Passo 2: YAML di base

Passo 3: File secrets.yaml

Passo 4: Compilare e caricare

Passo 5: Verifica

Passo 6: Test

What's Next?

Estendere le funzionalità

Configurazione consigliata

Materiali di riferimento

Avvio rapido (TL;DR)

Cronologia delle versioni