Componente Home Assistant (Apple) “HomeKit”

Produttore: Home Assistant Community
Disponibilità: incluso nell’HUB personale Home Assistant
Categoria: software
Tipologia: componente Home Assistant
Costo medio: gratuito
Difficoltà di implementazione: bassa
Valutazione inDomus: n.a.

Il componente “HomeKit” (inteso come Apple HomeKit) di Home Assistant serve per esporre le entità presenti in configurazione Home Assistant verso l’applicazione “Casa” di Apple iOS/macOS.Apple Logo

In pratica, gli utenti Apple che non vogliano utilizzare l’app “Home Assistant Companion” 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).
Infatti, una volta esposte le entità Home Assistant verso Apple HomeKit Siri sarà automaticamente in grado di “vederle” e governarle.

ATTENZIONE. Questo componente non è da confondersi col componente “iOS“, il quale serve a tutt’altro, ovvero a far sì che che l’app “Home Assistant Companion” per Apple iOS riesca a collegarsi correttamente al nostro Home Assistant e offrirgli le proprie funzionalità (device tracking, notifiche push eccetera).

ATTENZIONE. Questo componente non è da confondersi nemmeno col componente “HomeKit controller support“, il quale serve a fare in modo che Home Assistant riconosca automaticamente eventuali componenti compatibili Apple HomeKit e “farli propri”, permettendogli quindi di censirli e controllarli.

INDICE

Requisiti base

Per gli utenti di Home Assistant installato su Raspberry in modalità Raspbian+Home Assistant o HASSBIAN potrebbe essere necessaria l’installazione della libreria aggiuntiva Avahi per la compatibilità col servizio Apple Bonjour.

Per l’installazione, eseguire il comando:

sudo apt-get install libavahi-compat-libdnssd-dev

Gli utilizzatori della distribuzione HASSIO non hanno bisogno di alcuna installazione aggiuntiva.

Configurazione

Per abilitare le funzioni del componente “HomeKit” è sufficiente aggiungere, nella configurazione di Home Assistant, il seguente blocco minimale:

# Esempio di configurazione standard
homekit:

Dopo aver riavviato Home Assistant, presso il frontend web apparirà un riquadro contenente il PIN dedicato ad Apple HomeKit:

Home Assistant - HomeKit Code

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.

include_domains (lista, opzionale) Elenca i domini da includere
include_entities (lista, opzionale) Elenca le entità da includere
exclude_domains (lista, opzionale) Elenca i domini da escludere
excude_entites (lista, opzionale) Elenca le entità da escludere
entity_config (mappa, opzionale) Definisce personalizzazioni di singole entità verso HomeKit. Ogni nome_entità permette una propria personalizzazione (eg. light.cucina)

nome_entità
name (stringa, opzionale) Il nome dell’entità presso l’app Apple “Casa”
code (stringa, opzionale) Il codice per armare/disarmare un allarme o aprire/chiudere una serratura. Applicabile solo alle entità di tipo”Alarm Control Panel” e “Lock” (default: nessun codice)
feature_list (lista, opzionale) Valido solo per le entità di tipo “Media Player”. L’elenco può contenere solo elementi previsti nella piattaforma in uso (eg. “Broalink IR Media Player” usata per domotizzare TV, Impianti Hi-Fi ecc.)

feature (stringa, richiesta) Nome della feature disponibile per l’entità in fase di personalizzazione. Esempi validi sono “on_off“, “play_pause” ecc.
type (stringa, opzionale) Specifica il tipo di accessorio da presentare ad Apple “Casa” in caso l’entità di partenza sia si tipo “Switch“. Tipologie valide sono “faucet”, “outlet”, “shower”, “sprinkler”, “switch” e “valve”.

HomeKit effettua un caching di questa proprietà, quindi in caso questa configurazione venga cambiata, affinché abbia effetto presso Apple “Casa” è necessario rimuovere l’integrazione (il BRIDGE) e rimetterlo.

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 “”.

Poniamo l’esempio di avere delle entità 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:

  1. stoppando Home Assistant
  2. cancellando il file .HOMEKIT.STATE
  3. 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:

  1. stoppare Home Assistant
  2. cancellare il file .HOMEKIT.STATE
  3. modificare la configurazione di Home Assistant (vedi a seguire)
  4. 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. 


Home Assistant iconATTENZIONE: ricorda che sul nostro community FORUM c'è una sezione ad hoc dedica a Home Assistant, per qualsiasi dubbio, domanda, informazione nel merito specifico di queste componenti.

Dubbi? Perplessità? Fai un salto sul FORUM o sulla CHAT @DISCORD!
Questa pagina è coperta dalla licenza Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International Licenseil che significa che puoi liberamente condividerlo, senza modificarlo, citando il link della fonte.