Come collegare un Sonoff Mini a Home Assistant con ESPHome

Come usare un Sonoff Mini con ESPHome e Home Assistant in locale, con file corretto e avvertenze di sicurezza sui 230 V.

Ultimo aggiornamento: 7 novembre 2026. Versioni testate: Home Assistant Core 2026.11.0, Supervisor 2026.10.5, Operating System 18.4, Frontend 20261028.4 (su Raspberry Pi 5), ESPHome Device Builder 2026.10.2.

Avvertenza di sicurezza prima di iniziare. Il Sonoff Mini si collega alla rete elettrica di casa a 230 V, che può essere letale. Questa guida spiega la parte software. Per la parte elettrica: stacca sempre la corrente dal quadro (interruttore generale o magnetotermico del circuito) e verifica l’assenza di tensione prima di toccare qualunque filo; non lavorare mai con l’impianto acceso; usa solo prodotti con marcatura CE, in scatole di derivazione adatte e con il circuito protetto da un fusibile o magnetotermico di taglia corretta. Se non hai esperienza con gli impianti, fai installare il modulo da un elettricista abilitato: gli interventi sull’impianto elettrico andrebbero affidati a personale qualificato, e in molti casi la normativa lo richiede. Non descrivo qui i collegamenti dei fili, perché vanno fatti seguendo il manuale del produttore e le norme.

Il Sonoff Mini è un piccolo modulo che si nasconde dietro un interruttore a muro e lo rende “smart”, senza cambiarne l’aspetto. Con il software originale dipende dal cloud del produttore. Con ESPHome invece parla direttamente con Home Assistant, dentro casa tua. Io li uso per le luci di sala, laboratorio, bagno e per la luce del portone (l’apertura del portone è affidata a un altro dispositivo, non Sonoff).

Cosa otterrai

  • Un Sonoff Mini che si comanda da Home Assistant e continua a funzionare con l’interruttore a muro.
  • Un file ESPHome corretto e commentato, con chiavi e password messe al sicuro.
  • Un’idea chiara dei rischi e dei limiti del metodo di caricamento senza cavi.

Prima di tutto: quale modello hai?

Esistono più versioni del Mini (Mini, MiniR2, MiniR3, MiniR4) e non tutte hanno lo stesso chip. Il file di questa guida vale per le versioni con chip ESP8285, come il Mini e il MiniR2, che ESPHome gestisce come scheda esp8285. Le versioni più recenti possono avere un chip diverso e richiedere una configurazione diversa. I miei Mini hanno il chip ESP8285, quindi il file qui sotto è quello che uso io.

Cosa serve

Alcuni link in questa pagina sono link di affiliazione: se acquisti da lì io ricevo una piccola commissione, senza alcun costo per te. Trovi i dettagli nella pagina Trasparenza e affiliazioni.

  • Sonoff Mini con marcatura CE
  • ESPHome Device Builder già installato in Home Assistant
  • Un computer e una rete Wi-Fi a 2,4 GHz
  • Un elettricista abilitato, se non hai esperienza con l’impianto
  • Per il caricamento via cavo: un adattatore USB-seriale a 3,3 V (io uso il DSD TECH SH-U09G), un saldatore a punta fine e fili sottili

Come ho caricato ESPHome: via cavo seriale

Ho aggiornato sia i Sonoff Mini sia un Sonoff Basic con un cavo e un’interfaccia USB-seriale. La regola che non si discute: il modulo non deve essere collegato a nessuna fonte di energia elettrica. Niente 230 V, niente impianto: durante la programmazione si alimenta solo dall’adattatore, a 3,3 V. Collegare l’adattatore a un modulo ancora connesso alla rete può essere letale e distruggere anche il computer.

  1. Stacca il modulo dall’impianto, dal quadro, e lavora su un tavolo, con il modulo smontato e senza fili a 230 V collegati. Meglio ancora se lo programmi prima di montarlo.
  2. Individua i contatti di programmazione sulla scheda (alimentazione 3,3 V, massa, TX, RX e, a seconda del modello, un contatto che attiva la modalità di programmazione). Dove sono lo trovi nella pagina del tuo modello su devices.esphome.io: cambiano da un modello e da una revisione all’altra.
  3. Io ho saldato i cavi direttamente sulla scheda, con il minimo indispensabile di stagno per tenerli fermi durante l’aggiornamento. Il modulo è piccolo e delicato: usa un saldatore a punta fine, lavora in un ambiente ben aerato e non scaldare troppo i contatti.
  4. Imposta l’adattatore a 3,3 V prima di collegarlo. TX del modulo va su RX dell’adattatore e RX su TX.
  5. Collega l’adattatore al computer, premi Install nel Device Builder e scegli il collegamento al computer. Dopo la prima installazione, gli aggiornamenti arrivano via Wi-Fi.

Prima di rimontare il modulo: togli i cavi e controlla che non restino residui di stagno o fili che possano toccare le parti a 230 V. Il montaggio e il collegamento all’impianto vanno fatti con l’impianto spento (o da un elettricista).

Esiste anche una via Wi-Fi (la modalità DIY di Sonoff). Non l’ho usata e non la descrivo, perché richiede di tenere il modulo alimentato dalla rete. Un errore nel caricamento può rendere il modulo inutilizzabile: per questo preferisco il cavo, che permette sempre di recuperarlo.

Il file di configurazione ESPHome

Crea un nuovo dispositivo vuoto nel Device Builder, chiamalo per esempio luce-soggiorno e incolla questa configurazione. I pin sono quelli indicati dalla pagina del Sonoff Mini su devices.esphome.io: il relè sta sul pin 12, il pulsante sul pin 0, l’ingresso dell’interruttore a muro sul pin 4 e il LED blu sul pin 13.

substitutions:
  device_name: luce-soggiorno
  friendly_name: "Luce soggiorno"
  device_ip: 192.168.1.xxx

esphome:
  name: ${device_name}

esp8266:
  board: esp8285

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  manual_ip:
    static_ip: ${device_ip}
    gateway: xxx.xxx.xxx.xxx
    subnet: 255.255.255.0
  ap:
    ssid: "${device_name}-hotspot"
    password: !secret luce_soggiorno_ap_password

captive_portal:

logger:
  level: INFO

api:
  encryption:
    key: !secret luce_soggiorno_api_key

ota:
  - platform: esphome
    encryption:

binary_sensor:
  # pulsante sul corpo del modulo
  - platform: gpio
    pin: GPIO0
    id: pulsante
    internal: true
    filters:
      - invert:
      - delayed_off: 10ms
    on_press:
      - switch.toggle: rele_1

  # interruttore a muro collegato all'ingresso S2
  - platform: gpio
    name: "${friendly_name} interruttore"
    pin: GPIO4
    id: interruttore_muro
    on_press:
      - switch.toggle: rele_1
    on_release:
      - switch.toggle: rele_1

switch:
  - platform: gpio
    name: "${friendly_name}"
    icon: "mdi:lightbulb-outline"
    pin: GPIO12
    id: rele_1
    restore_mode: RESTORE_DEFAULT_OFF

status_led:
  pin:
    number: GPIO13
    inverted: true

Alcuni dettagli utili:

  • Indirizzo e rete. L’indirizzo 192.168.1.50 e il gateway 192.168.1.1 sono esempi: devi usare i valori della tua rete. Nella guida sull’IP fisso spiego come controllarli. In alternativa togli tutto il blocco manual_ip e lascia scegliere il router.
  • Icona. Il nome dell’icona usa il trattino normale (mdi:lightbulb-outline). Con il trattino basso l’icona non viene trovata.
  • Perché due volte switch.toggle. Un interruttore a muro tradizionale, quando cambia posizione, genera sia “premuto” sia “rilasciato”: invertendo il relè in entrambi i casi la luce risponde a qualunque scatto dell’interruttore.
  • Ripristino dopo un blackout. RESTORE_DEFAULT_OFF riporta lo stato precedente e, se non c’è, parte spento.
  • Chiavi e password. Sono tutte nel file secrets.yaml con nomi diversi per ogni dispositivo. Per generare una chiave nuova usa lo strumento nella pagina ufficiale del componente API di ESPHome. Non riutilizzare mai quelle di un altro modulo.
  • Aggiornamenti cifrati. La riga encryption: vuota sotto ota riusa la chiave dell’API.
Il Sonoff Mini nel Device Builder di ESPHome, con il file di configurazione del dispositivo

Aggiungerlo a Home Assistant

Dopo il primo avvio apri Impostazioni → Dispositivi e servizi: il modulo compare come “Rilevato”. Premi Configura e, se richiesto, inserisci la chiave API. Ti compariranno l’interruttore (la luce) e il sensore dell’interruttore a muro.

SONOFF mini dopo conversione a ESPHome

Prova prima con il comando da Home Assistant, poi con l’interruttore a muro, entrambi con il coperchio del frutto montato e senza toccare nulla.

Nella mia casa i Sonoff Mini comandano le luci di sala, laboratorio, bagno e portone.

Problemi comuni

  • La luce si accende da sola o fa l’inverso. Controlla come è collegato l’interruttore a muro e il tipo di interruttore. Fai verificare il cablaggio da un elettricista, a impianto spento.
  • Il modulo non compare in Home Assistant. Controlla il Wi-Fi a 2,4 GHz, il nome e la password nei secrets e leggi i log dal Device Builder.
  • Il LED lampeggia a lungo. Di solito il modulo non riesce a collegarsi alla rete: dopo alcuni minuti può comparire l’hotspot di emergenza.
  • Errore sulla chiave API. La chiave in Home Assistant e quella nel file non coincidono.

Riepilogo

Il Sonoff Mini diventa locale e indipendente dal cloud con ESPHome. La parte pericolosa è l’impianto a 230 V: stacca sempre dal quadro, usa materiale con marcatura CE e, se non sei esperto, chiama un elettricista. Per il software usa il file corretto qui sopra, con le chiavi nei secrets.

Articoli correlati

Fonti

Lascia una risposta