Thread border router e Matter in Home Assistant: aggiungere i dispositivi

Per portare in Home Assistant una presa, una lampadina o un sensore Matter vi serve il telefono, Android o iPhone, con l’app Companion. La guida è per chi ha già Home Assistant funzionante e vuole aggiungere il primo dispositivo Matter. Per i dispositivi Thread aiuta anche a capire quale border router usare: quello che avete già in casa, Apple o Google, oppure Home Assistant stesso con l’app OpenThread Border Router. I passaggi e i comandi sono quelli della documentazione ufficiale di Home Assistant, elencata in fondo.

Cosa serve

• Sistemi coperti: Home Assistant OS, con l’app Companion su Android 8.1 o successivo oppure su iPhone con iOS 16 o successivo (nella sezione sui problemi la documentazione indica come minimo iOS o iPadOS 16.4). Per Matter, Home Assistant OS è l’unica installazione supportata.
• Per i dispositivi Matter che usano Thread serve Home Assistant OS versione 10 o successiva. È richiesta anche l’ultima versione di Home Assistant.
• Un sistema a 64 bit, perché l’app ufficiale Matter Server non è supportata sulle piattaforme a 32 bit.
• Il supporto IPv6 attivo su Home Assistant, con il traffico IPv6 multicast che arriva liberamente dalla rete di casa all’host. Non servono una connessione Internet con IPv6 né un server DHCPv6.
• Un telefono con il Bluetooth acceso, da tenere vicino al dispositivo (e al border router, se il dispositivo usa Thread). Per i dispositivi Wi-Fi il telefono deve stare sulla stessa rete a 2,4 GHz in cui funzioneranno i dispositivi.
• Su Android è consigliata la versione 12 o successiva. Serve l’app Companion completa installata dal Play Store, con Google Play Services aggiornati e una configurazione Android normale con account Google, senza versioni alternative di Android. Il permesso di posizione dell’app va impostato su Allow all the time: durante l’abbinamento l’app lavora in background e, con il permesso limitato all’uso dell’app, Android le nasconde il nome della rete Wi-Fi.
• Su iPhone serve l’ultima versione dell’app Companion. L’app per Mac non può aggiungere dispositivi Matter.
• Il QR code o il codice numerico di configurazione del dispositivo. Se sta solo nel libretto, fategli una foto e conservatela: dopo un reset, senza quel codice il dispositivo non si può più abbinare.

Controllare i requisiti e preparare Home Assistant

Se Home Assistant non è ancora installato, partite dalla nostra guida base all’installazione. Andate in Settings > System > Network e controllate che IPv6 sia su Automatic o statico, secondo come è fatta la vostra rete. Nel dubbio la documentazione di Home Assistant su Matter indica Automatic.

Poi serve l’integrazione Matter, che lavora con un’app separata, il Matter Server, che fa da controller (le app prima si chiamavano add-on):

1. Aprite Settings > Devices & services e aggiungete l’integrazione Matter.
2. Alla richiesta Select the connection method, su un’installazione Home Assistant OS normale selezionate Submit: viene installata l’app ufficiale Matter Server.
3. Se il server Matter gira già in un’altra app o in un container vostro, togliete la spunta, selezionate Submit e nel passaggio successivo inserite l’URL del server.

Chi usa Home Assistant in un container può avviare l’immagine Docker del Matter server, seguendo i requisiti della sua pagina GitHub. Il Matter Server in un container Docker autonomo, però, non è supportato.

Un dispositivo nuovo si aggiunge solo dall’app Companion. Dal browser compare il messaggio You need to use the Home Assistant Companion app on your mobile phone to add Matter devices.

Capire se vi serve un border router Thread

Se il dispositivo ha il logo Matter e quello del Wi-Fi, oppure si collega via Ethernet, il border router non vi serve: passate direttamente al percorso per Android o per iPhone. Attenzione: il logo Thread da solo non garantisce Matter. Cercate sempre il logo Matter o una conferma del produttore.

Se c’è il logo Built on Thread: requires border router, il dispositivo usa solo Thread e non può collegarsi al Wi-Fi. Vi serve allora un border router collegato alla rete di casa, cioè un apparecchio che fa da ponte tra la rete Thread e il Wi-Fi o l’Ethernet. Spesso è una funzione in più di un altro apparecchio: il Nest Hub (2nd gen), per esempio, è uno smart display che contiene anche un border router Thread. Secondo la documentazione di Home Assistant su Thread, con Home Assistant funzionano questi:

• Google: Nest Hub (2nd gen), Nest Hub Max, Nest Wifi Pro (Wi-Fi 6E), Nest Wifi, Google TV Streamer (4K).
• Apple: HomePod (2nd generation), HomePod mini, Apple TV 4K (3rd generation) Wi-Fi + Ethernet, Apple TV 4K (2nd generation).
• Altri: la documentazione nomina in modo generico anche aziende come Nanoleaf e Amazon, senza indicare i modelli.

Usare uno di questi apparecchi non vuol dire mettere i dispositivi nell’ecosistema Apple o Google. Home Assistant li usa solo per arrivare alla rete Thread, e il border router inoltra dati cifrati senza poterli leggere. L’alternativa è fare di Home Assistant stesso il border router, con l’app OpenThread Border Router e un adattatore Thread.

Per sapere se in casa c’è già una rete Thread, aprite Settings > Connectivity > Thread. Se la voce non c’è, aggiungete prima l’integrazione Thread da Settings > Devices & services > Add integration. Se sotto Preferred network leggete You don’t have a preferred network yet. e in Other networks non c’è nulla, non avete ancora una rete Thread.

Per un dispositivo Thread l’ordine dei passaggi dipende dal border router che userete:

• Border router Apple o Google già in casa: aggiunto dall’app Companion, il dispositivo entra nella rete Thread preferita del telefono. Usate il telefono di quell’ecosistema (iPhone per una rete Apple, Android per una rete Google) e passate all’abbinamento. La sezione «Usare il border router Thread che avete già» serve a far conoscere quella rete anche a Home Assistant. Se in casa avete sia una rete Apple sia una Google, dovete scegliere a quale delle due appoggiarvi.
• Home Assistant come border router: prima seguite «In alternativa: fare di Home Assistant il border router con OpenThread Border Router», poi «Sincronizzare le credenziali Thread sul telefono», e solo dopo l’abbinamento da Android o da iPhone. Se saltate quei due passaggi il telefono non conosce la rete e l’abbinamento si ferma sull’errore this device requires a border router.

Aggiungere il dispositivo Matter da Android

Durante l’abbinamento il telefono manda al dispositivo, via Bluetooth, le credenziali della rete. Da lì in poi il dispositivo comunica con la sua interfaccia, Wi-Fi o Thread. Se usa Thread entra nella rete Thread preferita del telefono.

1. Aprite l’app Home Assistant sul telefono.
2. Date corrente al dispositivo, collegandolo alla presa o inserendo la batteria. Quasi tutti entrano da soli in modalità di abbinamento; per alcuni va attivata a mano, come spiega il libretto.
3. Se compare il pop-up Scan the QR code, inquadrate il codice. Alla richiesta Choose an app scegliete Home Assistant, poi selezionate Done e Add device.
4. Se il pop-up non compare, andate in Settings > Connectivity > Matter, toccate Add device e rispondete No. It’s new.
5. Inquadrate il QR code, oppure scegliete Setup without QR-code per inserire il codice a mano. L’abbinamento può richiedere qualche minuto.
6. Alla fine selezionate Done.

In Home Assistant si apre la finestra Device added. Potete dare un nome al dispositivo e assegnarlo a un’area, cioè la stanza in cui sta, poi premere Finish, oppure Skip and finish se non avete cambiato nulla. Quando si apre la pagina del dispositivo, potete già usarlo.

Aggiungere il dispositivo Matter da iPhone

1. Aprite l’app Home Assistant e andate in Settings > Connectivity > Matter.
2. Toccate Add device e rispondete No. It’s new.
3. Inquadrate il QR code con la fotocamera, oppure selezionate More options… per inserire il codice a mano.
4. Selezionate Add to Home Assistant e aspettate: l’abbinamento può richiedere qualche minuto.
5. Con schede di test o dispositivi beta può comparire Uncertified Accessory. In quel caso scegliete Add Anyway.
6. Se vi viene chiesto un Accessory Name, scrivete quello che volete e premete Continue. Il nome serve solo a iOS e in Home Assistant non si vede.
7. Al termine selezionate Done.

Come su Android, nella finestra Device added scegliete nome e area e chiudete con Finish o Skip and finish.

Usare il border router Thread che avete già

Con questi passaggi Home Assistant impara la rete Thread preferita del telefono, quella in cui entrano i dispositivi aggiunti dall’app Companion, e la fa diventare anche la sua rete preferita. Usate il telefono dell’ecosistema giusto (Android per una rete Google, iPhone per una rete Apple), collegato alla stessa rete Wi-Fi del border router.

1. Nell’app Companion andate in Settings > Connectivity > Thread.
2. Selezionate Send credentials to Home Assistant. Su Android compare il messaggio Imported credential.
3. Aggiornate la schermata. Accanto alla rete compare l’icona che indica che Home Assistant ne conosce le credenziali.
4. Selezionate Make preferred network.

L’app per Android invia la rete preferita del telefono. Quella per iPhone invia la rete preferita e anche le altre reti Thread a cui l’app ha accesso.

A questo punto potete anche aggiungere un border router di Home Assistant installando l’app OpenThread Border Router, come nella sezione seguente. Se l’adattatore non ha ancora una rete Thread, si unisce alla rete preferita invece di crearne una nuova. Se l’adattatore è multiprotocollo, la rete preferita deve usare lo stesso canale: se è diverso, il border router crea una rete Thread nuova invece di unirsi a quella esistente.

Con i border router Apple c’è un limite: per ora gli aggiornamenti Matter da Home Assistant non funzionano per i dispositivi Thread su una rete con border router Apple. Gli aggiornamenti possono arrivare dall’ecosistema Apple Home.

In alternativa: fare di Home Assistant il border router con OpenThread Border Router

Questa strada vale se non avete ancora nessuna rete Thread. Home Assistant ne crea una nuova chiamata ha-thread-xxxx, dove le ultime quattro cifre identificano la rete. Home Assistant Yellow, Connect ZBT-1 e Connect ZBT-2 di fabbrica usano Zigbee e non Thread: per attivare Thread seguite la procedura dedicata a ciascun modello, che prevede passaggi da fare a mano.

Con un adattatore Thread di un altro produttore servono Home Assistant OS con gli ultimi aggiornamenti, l’adattatore e un cavo di prolunga USB. Se l’adattatore supporta più protocolli, installate il firmware OpenThread come indica il produttore e annotate il baudrate.

1. Andate in Settings > Apps > OpenThread Border Router e selezionate Install.
2. Collegate l’adattatore alla prolunga e la prolunga al dispositivo su cui gira Home Assistant.
3. Nella stessa pagina aprite la scheda Configuration. In Device scegliete l’adattatore e in Baudrate il valore indicato dal produttore. Se non lo trovate, lasciate il predefinito 460800 o chiedete all’assistenza del produttore.
4. Salvate, avviate l’app (o riavviatela se è già attiva), aspettate che parta e guardate i log.
5. Se l’app va in crash o non comunica con l’integrazione Thread, cambiate l’opzione Hardware flow control e riprovate.

Home Assistant aggiunge da solo l’integrazione OpenThread Border Router. Per controllare aprite Settings > Connectivity > Thread: dovete vedere il vostro border router e, sotto Preferred network, il logo di Home Assistant.

Sincronizzare le credenziali Thread sul telefono

Se il border router è Home Assistant, il telefono non conosce ancora la nuova rete. Prima di aggiungere dispositivi Thread deve riceverne le credenziali, un po’ come la password del Wi-Fi.

• Android: nell’app Companion andate in Settings > Companion app > Troubleshooting, selezionate Sync Thread credentials e seguite le istruzioni. Alla fine compare Added network from Home Assistant to this device.
• iPhone: nell’app Companion andate in Settings > Connectivity > Thread e, in fondo al riquadro della rete preferita, selezionate Send credentials to phone.

Se qualcosa va storto

• «this device requires a border router»: un dispositivo Thread ha bisogno di un border router, e il telefono deve conoscere la rete. Rifate i passaggi sul border router e sulla sincronizzazione delle credenziali.
• «Matter is currently unavailable» su Android: Google Play Services può metterci fino a 24 ore per scaricare i moduli Matter. In Settings > Google > Devices & Sharing deve esserci la voce Matter devices. Potete anche reinstallare l’app Companion, oppure installare o reinstallare Google Home, che può far ripartire l’installazione dei moduli.
• Bloccato su «Checking network connectivity»: per un dispositivo Thread, avvicinate il telefono al border router e al dispositivo. Per un dispositivo Wi-Fi, mettete il telefono sulla rete a 2,4 GHz.
• Il dispositivo non si abbina: ricontrollate i requisiti. Assicuratevi che il dispositivo sia ancora in modalità di abbinamento, perché di solito ci resta poco tempo, e se serve rimettetelo. Riavviate il telefono e controllate che il Wi-Fi mesh non filtri il multicast: nelle sue impostazioni cercate opzioni come multicast, IGMP snooping o mDNS.
• Più reti Thread separate: di solito ogni produttore crea la propria rete, e i dispositivi non passano da una all’altra. In Settings > Connectivity > Thread i border router sono raggruppati per rete. Per unire un border router di Home Assistant a una rete esistente seguite la sezione sul border router che avete già.

Se nei log dell’app OTBR compare l’avviso «IPv6 routing/forwarding is not enabled», oppure i dispositivi Thread entrano nella rete ma non si riescono a raggiungere, su Home Assistant OS l’IPv6 potrebbe essere disattivato in Docker. Per questa impostazione non c’è una voce nell’interfaccia. Aprite l’app Terminal & SSH e controllate:

ha docker info

Guardate il valore di enable_ipv6 e passate al comando seguente solo se è null o false. Attenzione: il comando modifica la configurazione di Docker, quindi non usatelo se il valore risulta già attivo.

ha docker options --enable-ipv6=true

La modifica vale solo dopo il riavvio dell’host. Attenzione: il prossimo comando riavvia l’intera macchina, e finché non riparte Home Assistant e i dispositivi che gestisce non rispondono.

ha host reboot

Se Home Assistant OS gira in una macchina virtuale, controllate anche che la VM abbia connettività IPv6.

Tornare indietro: rimuovere un dispositivo

Per eliminare un dispositivo da Home Assistant, aprite la sua pagina, toccate il menu a tre puntini e scegliete Delete. Per toglierlo solo da un altro controller, come Google Home o Apple Home:

1. Andate in Settings > Connectivity > Matter e selezionate Devices.
2. Scegliete il dispositivo. Nella sezione Device info toccate il menu a tre puntini accanto a Share device, poi Manage fabrics.
3. Rimuovete il controller dall’elenco. Per Apple Home togliete anche la voce nel Portachiavi di Apple.

Se dovete segnalare un problema, scaricate il file di diagnostica: in Settings > Devices & services, sulla card dell’integrazione Matter, toccate il menu a tre puntini e poi Download diagnostics.

Documentazione di riferimento

• Documentazione di Home Assistant — integrazione Matter, consultata il 4 novembre 2026.
• Documentazione di Home Assistant — integrazione Thread, consultata il 4 novembre 2026.

Leggi anche

• Home Assistant OS su Raspberry Pi 4 o 5: guida all’installazione
• Zigbee2MQTT con Docker: installazione e collegamento a Home Assistant