Come integrare Aqara in Home Assistant: Zigbee o Matter

Aqara non identifica un solo protocollo: alcuni dispositivi usano Zigbee, altri Matter su Wi-Fi o Thread, altri ancora dipendono da un hub Aqara. La procedura corretta parte dal logo e dal modello del dispositivo. Zigbee e Matter sono hardware/protocolli di comunicazione; ZHA, Zigbee2MQTT, Matter Server e Home Assistant sono software distinti.

Prerequisiti & Hardware Necessario

• Dispositivo Aqara con modello identificato e firmware aggiornato secondo la documentazione del produttore.
• Per Zigbee: un coordinatore Zigbee funzionante con ZHA o Zigbee2MQTT. Non associare lo stesso dispositivo contemporaneamente a due reti Zigbee.
• Per Matter su Wi-Fi: rete IPv6/mDNS funzionante e Home Assistant con Matter Server.
• Per Matter su Thread: Thread Border Router operativo oltre al controller Matter. Un coordinatore Zigbee non è automaticamente un Thread Border Router.
• Per un hub Aqara usato come bridge: modello compatibile con Matter Bridge e app Aqara per attivare la modalità di pairing.
• Nessun link d’acquisto viene inserito: il metodo dipende dal modello Aqara e non esiste un hardware universale.

Procedura passo-passo

1. Leggi modello e logo. Annota il codice completo e verifica se trovi il logo Zigbee, Matter, Wi-Fi o Thread. Un sensore Aqara Zigbee va associato a un coordinatore Zigbee; un sensore Matter va aggiunto tramite Matter. Non usare una procedura Zigbee su un dispositivo Matter.
2. Scegli un solo percorso. Per Zigbee usa ZHA oppure Zigbee2MQTT. Per Matter usa l’integrazione Matter di Home Assistant. Se possiedi un hub Aqara compatibile, puoi aggiungere il bridge via Matter e mantenere il controllo anche nell’app Aqara, ma le funzioni esposte possono essere inferiori a quelle native.
3. Prepara Zigbee, se applicabile. Verifica che il coordinatore sia online, apri Aggiungi dispositivo in ZHA oppure Permit join in Zigbee2MQTT e limita la finestra di pairing. Tieni il dispositivo vicino al coordinatore durante l’associazione.
4. Metti Aqara Zigbee in pairing. Segui il manuale del modello e usa il pulsante di reset/pairing previsto. Un reset di fabbrica può cancellare associazioni e impostazioni; non usare tempi o sequenze di un modello diverso.
5. Attendi l’intervista e assegna l’area. In ZHA/Zigbee2MQTT aspetta che il dispositivo venga identificato e che le entità siano disponibili. In Home Assistant assegna area, nome e funzione. Per i sensori a batteria il dispositivo può dormire e mostrare temporaneamente uno stato offline.
6. Prepara Matter, se applicabile. In Home Assistant vai in Impostazioni → Dispositivi e servizi, aggiungi Matter e, su Home Assistant OS, installa o seleziona il Matter Server ufficiale quando richiesto. La documentazione ufficiale indica Home Assistant OS come installazione supportata per l’app Matter; container e installazioni diverse richiedono una configurazione separata.
7. Verifica la rete Matter. Per Matter su Wi-Fi controlla IPv6, multicast DNS e isolamento client. Per Matter su Thread controlla che il Thread Border Router sia online e che il telefono possa completare il commissioning. Matter usa IP e non trasforma un coordinatore Zigbee in un border router Thread.
8. Aggiungi Aqara Matter. Nell’app Aqara metti il dispositivo o l’hub in modalità Matter pairing e usa il codice QR/setup code indicato. In Home Assistant scegli Aggiungi dispositivo Matter, scansiona il codice o inseriscilo manualmente e completa il commissioning sulla stessa rete locale.
9. Usa un hub Aqara come Matter bridge solo se necessario. Attiva il bridge Matter nell’app del modello compatibile e aggiungilo a Home Assistant. Il bridge può esporre solo un sottoinsieme di sensori, luci, serrature o interruttori; non assumere che tutte le funzioni dell’app Aqara diventino entità Matter.
10. Controlla le entità. Verifica classe, unità, batteria e disponibilità. Per sensori di presenza o rilevamento avanzato, controlla quali attributi vengono realmente esposti dal protocollo scelto.
11. Configura automazioni dopo il test manuale. Usa una singola entità Aqara come trigger, testa l’azione e poi aggiungi condizioni. Evita di creare automazioni basate su nomi generici finché il dispositivo non è stato assegnato all’area corretta.
12. Proteggi la rete. Non isolare mDNS/IPv6 senza configurare il reflector o le regole necessarie. Mantieni Zigbee/Matter locali, aggiorna firmware e non condividere setup code o credenziali Aqara.

Verifica del funzionamento

1. Controlla che il dispositivo Aqara compaia una sola volta nel percorso scelto.
2. Attiva il sensore, il pulsante o il relay e verifica l’evento in Home Assistant.
3. Riavvia Home Assistant e il coordinatore/hub: il dispositivo deve tornare disponibile senza un nuovo pairing.
4. Per Matter verifica nei dettagli del dispositivo il percorso Thread/Wi-Fi e lo stato del Matter Server.
5. Per Zigbee controlla mappa, qualità del collegamento e batteria senza interpretare un end device addormentato come guasto.

Problemi comuni

FAQ essenziali

Posso usare Aqara con ZHA e Zigbee2MQTT insieme?

Sì, ma ogni rete richiede un coordinatore separato e un dispositivo Zigbee può appartenere a una sola rete alla volta. Per una configurazione semplice scegli un solo gestore Zigbee.

Un hub Aqara è obbligatorio?

No, se il dispositivo è Zigbee e hai un coordinatore compatibile oppure se è Matter e hai il controller/trasporto richiesto. Un hub è necessario solo per funzioni o dispositivi che dipendono da esso.