Come integrare un dispositivo Sonoff Zigbee in Home Assistant con Zigbee2MQTT

Un dispositivo Sonoff Zigbee non usa il Wi-Fi e non si aggiunge come dispositivo eWeLink: comunica con un coordinatore Zigbee, che in questa guida è gestito da Zigbee2MQTT, e Home Assistant riceve le entità tramite MQTT. Sonoff è l’hardware; Zigbee2MQTT, MQTT e Home Assistant sono software distinti. La sequenza è valida per modelli supportati, ma il reset e il tipo di alimentazione dipendono dal modello esatto.

Prerequisiti & Hardware Necessario

• Dispositivo Sonoff Zigbee supportato da Zigbee2MQTT, con modello identificato dall’etichetta, per esempio un sensore, pulsante, presa o relè della serie Zigbee.
• Coordinatore Zigbee già funzionante in Zigbee2MQTT e collegato al server Home Assistant.
• Broker MQTT raggiungibile da Zigbee2MQTT e Home Assistant, con credenziali configurate.
• Manuale del modello Sonoff per tensione, cablaggio, reset e modalità di pairing. Per i dispositivi a rete elettrica il cablaggio deve essere eseguito a impianto disalimentato da personale qualificato.
• Nessun link d’acquisto viene inserito: il modello Sonoff va scelto in base a funzione, alimentazione e carico; non esiste un hardware unico necessario per questa procedura.

Procedura passo-passo

1. Identifica il modello. Leggi il codice completo, per esempio SNZB-01P, ZBMINIR2 o S26R2ZB. Non confondere la variante Zigbee con la versione Wi-Fi/eWeLink: la procedura e il firmware sono diversi.
2. Verifica il coordinatore e MQTT. In Zigbee2MQTT controlla che il coordinatore sia online e che il broker MQTT sia connesso. In Home Assistant verifica che l’integrazione MQTT sia configurata e che l’MQTT discovery sia attivo nel frontend di Zigbee2MQTT.
3. Apri temporaneamente il pairing. In Zigbee2MQTT apri Permit join e limita la durata alla finestra necessaria, per esempio 60 secondi. Se disponibile, scegli il coordinatore come destinazione del pairing; non lasciare la rete aperta permanentemente.
4. Metti Sonoff in modalità pairing. Esegui la procedura del manuale del modello: di norma consiste nel tenere premuto il pulsante di reset o pairing finché il LED segnala il riavvio della rete Zigbee. Non usare tempi o combinazioni di un altro modello. Per un dispositivo già associato, il reset può cancellare la rete precedente e le impostazioni locali.
5. Attendi l’intervista Zigbee. In Zigbee2MQTT aspetta che il dispositivo passi da interviewing a interview successful. Non togliere alimentazione durante l’intervista e non rinominare il dispositivo finché la procedura non è terminata.
6. Assegna un friendly name stabile. Usa un nome come sonoff_ingresso o presa_lavanderia, senza spazi e senza basarlo sull’indirizzo di rete Zigbee. L’indirizzo di rete può cambiare; l’identificativo IEEE resta quello del dispositivo.
7. Chiudi il pairing. Imposta Permit join su Disabled. Se il dispositivo supporta un install code, aggiungilo secondo la documentazione Zigbee2MQTT; per reti più restrittive configura passlist o blocklist senza perdere il backup della rete.
8. Controlla le entità in Home Assistant. Grazie a MQTT discovery, il dispositivo dovrebbe comparire in Impostazioni → Dispositivi e servizi → MQTT. Assegna area, nomi e categorie alle entità; disabilita solo quelle realmente inutili, non quelle necessarie per la diagnostica.
9. Verifica il tipo di dato. Per un relè controlla switch, per un sensore batteria controlla temperatura, umidità o batteria, per un pulsante controlla gli eventi o i sensori esposti dal modello. Le entità dipendono dal converter Zigbee2MQTT e dal firmware del dispositivo.
10. Configura un’automazione minima. Crea prima un’automazione di test, per esempio un pulsante Sonoff che accende una luce. Usa l’entità o l’evento mostrato dal dispositivo, non copiare un nome da un modello diverso.
11. Ottimizza la rete Zigbee. Se il Sonoff è alimentato a rete, può comportarsi da router Zigbee solo se il modello lo supporta; i dispositivi a batteria sono normalmente end device. Posiziona il coordinatore lontano da USB 3.x, router Wi-Fi e metallo e aggiungi router Zigbee alimentati a rete quando la topologia lo richiede.

Verifica del funzionamento

1. In Zigbee2MQTT verifica che il dispositivo sia online e che la pagina mostri il modello corretto.
2. Invia un comando dal frontend Zigbee2MQTT e controlla che lo stato torni in Home Assistant.
3. Aziona fisicamente il dispositivo o premi il pulsante e verifica che l’evento venga ricevuto senza ritardi anomali.
4. Riavvia Zigbee2MQTT e Home Assistant separatamente: il dispositivo deve ricomparire senza nuovo pairing.
5. Per i sensori a batteria, esegui il test subito dopo il risveglio: un end device può risultare offline mentre dorme senza essere guasto.

Problemi comuni

FAQ essenziali

Posso usare l’app eWeLink con questo metodo?

Un dispositivo Sonoff Zigbee associato al tuo coordinatore Zigbee2MQTT non viene controllato tramite eWeLink. Il percorso locale è Sonoff → Zigbee → coordinatore → Zigbee2MQTT → MQTT → Home Assistant.

Devo aggiornare il firmware prima del pairing?

Non sempre. Aggiorna solo con il firmware esatto del modello e una procedura compatibile; un firmware errato può rendere il dispositivo inutilizzabile o cambiare la compatibilità Zigbee.