| Produttore: Home Assistant Community Disponibilità: incluso nell’HUB personale Home Assistant Categoria: software Tipologia: componente Home Assistant Difficoltà di implementazione: bassa |
| Revisione scheda: 1.2 |
Il componente “HomeKit Bridge” di Home Assistant serve per esporre le entità presenti in configurazione Home Assistant verso Apple HomeKit, quindi verso l’applicazione “Casa” di Apple iOS/macOS.
In pratica, gli utenti Apple che non vogliano utilizzare l’app mobile di Home Assistant e vogliano al suo posto (oppure in affiancamento, perché no) utilizzare l’app “Casa” di Apple per controllare la propria domotica basata su Home Assistant altro non devono fare che configurare questo componente.
In pratica, è come se Home Assistant diventasse un BRIDGE/Gateway compatibile con Apple HomeKit.
Automaticamente – previa un’iniziale, semplice procedura – l’app “Casa” erediterà tutte le entità (luci, interruttori, sistemi clima ecc.) configurate presso Home Assistant. Qualsiasi azione effettuata da altri (o da automatismi in essere) agli stati di tali entità si rifletteranno sugli stati presso l’app “Casa”, e viceversa.
Se per esempio accendessimo una luce tramite Home Assistant, tale elemento apparirà immediatamente acceso anche sull’app “Casa”, e viceversa.
Le entità esportabili verso Apple “Casa” sono diverse: possono essere interi domini (eg. “tutte le luci”) o entità singole (eg. “la luce della cucina”). È altresì possibile configurare in modo selettivo cosa esporre e cosa no.
| Questo componente è particolarmente utile a chi possegga uno smart speaker Apple HomePod e voglia controllare la propria domotica basata su Home Assistant con l’assistente vocale Siri (o dispositivo che comunque disponga di tale assistente, vedi iPhone/iPad o macOS ultime versioni). Una volta esposte le entità Home Assistant verso Apple HomeKit, infatti, Siri sarà automaticamente in grado di “vederle” e governarle. A questo specifico tema abbiamo dedicato un FOCUS specifico. |
ATTENZIONE. Questo componente non è da confondersi nemmeno col componente HomeKit Device, il quale serve a fare in modo che Home Assistant riconosca automaticamente eventuali dispositivi compatibili Apple HomeKit e “farli propri”, permettendogli quindi di censirli e controllarli.
INDICE
- Requisiti base
- Configurazione
- Personalizzazione del componente
- Considerazioni varie
- Configurazione dei filtri
- Risoluzione dei problemi
Requisiti base
Per gli utenti di Home Assistant installato su Raspberry in modalità Home Assistant Core@Raspberry Pi OS potrebbe essere necessaria l’installazione della libreria aggiuntiva Avahi per la compatibilità col servizio Apple Bonjour.
Per l’installazione, eseguire il comando:
sudo apt install libavahi-compat-libdnssd-dev -y
Gli utilizzatori della distribuzione Home Assistant OS non hanno bisogno di alcuna installazione aggiuntiva.
Configurazione
Per abilitare le funzioni del componente “HomeKit Bridge” è sufficiente aggiungere, nella configurazione di Home Assistant, il seguente blocco minimale:
homekit:
Dopo aver riavviato Home Assistant, presso il frontend web apparirà un riquadro contenente il PIN dedicato ad Apple HomeKit:
A questo punto aprire l’applicazione “Casa” di iOS e premere su “Aggiungi accessorio“.
Dopodiché premere su “Non ho un codice” e successivamente “Inserire codice“.
Verrà richiesto di inserire il codice di cui sopra; inserirlo, poi attendere: al termine della procedura, le entità (almeno, quelle eleggibili) di Home Assistant appariranno elencate e controllabili presso “Casa“.
Personalizzazione del componente
Il componente prevede vari campi per personalizzare l’esposizione (nonché il filtraggio) delle entità verso HomeKit.
| homekit: | |||||||||||||
| autostart | (booleano, opzionale) Imposta l’integrazione con HomeKit come automatica all’avvio di Home Assistant (default: true) | ||||||||||||
| port | (intero, opzionale) Definisce la porta tcp/ip sulla quale far operare il BRIDGE verso HomeKit (default: 51827) | ||||||||||||
| name | (stringa, opzionale) Definisce il nome del BRIDGE presso l’app Apple “Casa” (default: “Home Assistant Bridge”). Il numero minimo di caratteri è 3, il massimo 25. | ||||||||||||
| ip_address | (stringa, opzionale) Specifica quale IP utilizzare (in caso il dispositivo che ospita Home Assistant abbia più interfacce/IP) per l’integrazione | ||||||||||||
| safe_mode | (booleano, opzionale) Da impostare a “true” in caso di problemi durante il pairing con l’app Apple “Casa” (default: false) | ||||||||||||
| filter | (mappa, opzionale) Definisce quali entità e/o domini includere/escludere dall’esposizione verso HomeKit. In assenza di questo blocco, Home Assistant espone tutto ciò che è eleggibile.
|
||||||||||||
| entity_config | (mappa, opzionale) Definisce personalizzazioni di singole entità verso HomeKit. Ogni nome_entità permette una propria personalizzazione (eg. light.cucina)
|
||||||||||||
Considerazioni varie
ACCESSORY ID
Il componente utilizza l’ID dell’entità presso Home Assistant per generare un corrispondente ID dell’accessorio presso HomeKit al quale associare tutte le personalizzazioni. Va da sé che un cambiamento dell’ID dell’entità farà smarrire ad Home Assistant le personalizzazioni precedentemente assegnategli da applicare verso HomeKit.
LIMITE ACCESSORI
HomeKit accetta fino a 100 accessori per BRIDGE. Cosa importante, da tenere a mente, quando si provvede a configurare le inclusioni e le esclusioni dei domini/entità in configurazione.
STORAGE PERSISTENTE
Purtroppo HomeKit non presenta uno storage persistente, il che significa che se all’avvio di Home Assistant determinate entità non sono ancora pronte all’uso (magari una data integrazione sta ancora avviandosi/censendo dei componenti), le corrispondenti entità presso Apple “Casa” spariranno.
Per evitare questo è consigliato di disabilitare l’auto-start e configurare delle automazioni tali da avviare il componente “HomeKit” solo quando sia effettivamente il momento.
Disattivare l’auto-start
Come spiegato, potrebbe tornare utile disattivare l’auto-start di questo componente:
homekit:
auto_start: False
Per avviare il componente in un secondo momento si potrà utilizzare il servizio “homekit.start“.
Poniamo l’esempio di avere delle entità basate su integrazione Z-Wave le quali, fin tanto che l’integrazione non sia effettivamente funzionante, ci impongono di non avviare “HomeKit”.
Un’automazione utile a tal fine potrebbe essere la seguente:
automation:
- alias: 'Avvio HomeKit al momento giusto'
trigger:
- platform: event
event_type: zwave.network_ready
- platform: event
event_type: zwave.network_complete
- platform: event
event_type: zwave.network_complete_some_dead
action:
- service: homekit.start
Come si vede, si attende che tutti gli eventi legati all’avvio di Z-Ware siano completati per avviare, successivamente, “HomeKit”.
Potrebbe anche semplicemente essere utile avviarlo dopo un tempo prefissato:
automation:
- alias: 'Avvio temporizzato di HomeKit'
trigger:
- platform: homeassistant
event: start
action:
- delay: 00:05 # Attende cinque minuti
- service: homekit.start
Configurazione dei filtri
Come anticipato, in assenza di filtri Home Assistant (in caso di attivazione del presente componente) non pone alcun limite ed espone qualunque entità verso HomeKit.
Un esempio di configurazione tipo:
homekit:
filter:
include_domains:
- alarm_control_panel
- light
exclude_entities:
- light.cucina
In questo caso si includono tutti gli eventuali “Alarm Control Panel” (sistemi d’allarme) e tutte le luci; si esclude invece una sola luce, quella della cucina.
I domini/entità supportati sono i seguenti:
| Componente | Tipologia | Descrizione |
|---|---|---|
| alarm_control_panel | Sistemi di sicurezza | Tutti i sistemi di sicurezza. |
| automation / input_boolean / remote / scene / script | Interruttori | Tutti componenti rappresentati come interruttori acceso/spento. |
| binary_sensor | Sensori | Supporta dispositivi di tipo “co2“, “door“, “garage_door“, “gas“, “moisture“, “motion“, “occupancy“, “opening“, “smoke” e “window“. Qualunque altro ricade nella tipologia “occupancy“. |
| climate | Termostati | Tutte le entità di tipo clima. |
| cover | Apertura porta garage | Tutte le chiusure che supportino “open” e “close” e abbiano “garage” quel “device_class” associata. |
| Scuri finestra | Tutti gli scuri che supportino “set_cover_position“. | |
| Tutti gli scuri che supportino “open_cover” e “close_cover” attraverso mapping di valori (aperto >=50, chiuso <50). | ||
| Tutti gli scuri che supportino “open_cover“, “stop_cover” e “close_cover” attraverso mapping di valori (aperto >70, chiuso <30, stop ogni valore nell’intervallo). | ||
| device_tracker | Sensori | Supporto per i device di tipologia “occupancy“. |
| fan | Ventilatori/ventole | Supporto per “on/off“, “direction” e “oscillating“. |
| light | Luci | Supporto per “on/off“, “brightness” e “rgb_color“. |
| lock | Serrature | Supporto per “lock” e “unlock“. |
| media_player | MediaPlayer | Rappresentati come una serie di interruttori i quali supportano “on/off“, “play/pause“, “play/stop“, “mute” in base alle “supported_features” e le liste “mode” previste per l’entità specifica. |
| sensor | Sensori di temperatura | Tutti i sensori termici che abbiano Celsius e/o Fahrenheit come unità di misura. |
| Sensori di umidità | Tutti i sensori di umidità che abbiano la percentuale come unità di misura. | |
| Sensori di qualità dell’aria | Tutti i sensori che abbiano “pm25” quale elemento delle proprie caratteristiche. | |
| Sensori di monossido di carbonio | Tutti i sensori che abbiano “co” quale elemento delle proprie caratteristiche. | |
| Sensori di anidride carbonica | Tutti i sensori che abbiano “co2” quale elemento delle proprie caratteristiche. | |
| Sensori di luminosità | Tutti i sensori che abbiano “lm” o “lx” quali elementi delle proprie caratteristiche. | |
| switch | Interruttori | Rappresentati come interruttori. Possono essere cambiati come tipologia usando il campo di personalizzazione “type“. |
| water_heater | Riscaldatori d’acqua | Tutti i riscaldatori d’acqua. |
Risoluzione dei problemi
Cancellazione del file .HOMEKIT.STATE
In caso di problemi con l’integrazione è possibile tornare al punto zero semplicemente:
- stoppando Home Assistant
- cancellando il file .HOMEKIT.STATE
- riavviando Home Assistant
Errori durante il pairing
In caso di problemi durante il pairing tra Home Assistant e l’applicazione Apple “Casa”, provvedere come segue:
- stoppare Home Assistant
- cancellare il file .HOMEKIT.STATE
- modificare la configurazione di Home Assistant (vedi a seguire)
- riavviare Home Assistant
Provare modificando la configurazione come segue:
logger:
default: warning
logs:
homeassistant.components.homekit: debug
pyhap: debug
homekit:
filter:
include_entities:
- demo.demo
Il PIN per il pairing non appare
Si potrebbe già aver utilizzato il pairing. Cancellare il file .homekit.state.
Home Assistant non appare come BRIDGE su Apple Casa
Solitamente è un problema di rete. Verificare di trovarsi sulla stessa rete locale di Home Assistant.
Provare anche cambiando la default_port.
Home Assistant (su Docker) non appare come BRIDGE su Apple Casa
Impostare network_mode: host
Home Assistant (su VirtualBox) non appare come BRIDGE su Apple Casa
Configurare la modalità di rete come networkbridge. Diversamente, il BRIDGE non verrà esposto alla rete (e quindi non funzionerà).
Il pairing fallisce – zeroconf error
Se il pairing fallisce dovrebbe apparire un errore NonUniqueNameException. Impostare la modalità “safe_mode“.
Il pairing fallisce – funziona solo con la configurazione di debug
Funziona solo se si include l’entità demo.demo, ma fallisce nelle condizioni di configurazione reale.
Purtroppo, alcune (rare) entità semplicemente non funzionano. Per risolvere è necessario discriminare una alla volta le entità fino a capire quale sia quella che crea problemi, magari utilizzando i domini per semplificare il compito.
Il pairing fallisce ma senza errori
Verificare di non aver superato il limite di 100 accessori.
Trovati ID duplicati quando si aggiunge un accessorio
Due entità condividono lo stesso ID. Risolvere il problema oppure escludere una delle due.
Errori nell’uso ordinario
Alcuni accessori non appaiono, per esempio gli Z-Wave
Vedi sopra alla voce “disattivare auto-start“.
Una nuova entità Home Assistant non appare su Apple “Casa”
Verificare di non aver escluso in configurazione il dominio al quale appartiene. Verificare che, se inclusa esplicitamente, sia scritta bene.
Un’entità è presente ma non funziona
Purtroppo, alcune (rare) entità semplicemente non funzionano. Per risolvere è necessario discriminare una alla volta le entità fino a capire quale sia quella che crea problemi, magari utilizzando i domini per semplificare il compito.
Tutte gli accessori presso Apple “Casa” risultano “non rispondere”
Verificare di non aver superato il limite di 100 accessori.
Accessory not responding – after restart or update
Verificare di non aver superato il limite di 100 accessori.
Alcuni accessori di tanto in tanto non funzionano
Purtroppo capita. C’è poco da fare. Solitamente riprendono a funzionare da soli.
| Questa pagina è redatta, manutenuta e aggiornata dallo staff di inDomus, un gruppo di persone molto diverse tra loro che trovi, per domande e supporto, sul forum e sulla chat del sito. Alcuni link sono taggati in qualità di affiliati Amazon e riceviamo un compenso dagli acquisti idonei, utile al sostenimento del sito, ma le nostre recensioni sono tutte indipendenti e non sponsorizzate. Se ti sei perso, a tua disposizione c'è la mappa. |