Componente Home Assistant “Xiaomi Gateway”

6 minuti di lettura
Produttore: Home Assistant Community
Disponibilità: incluso nell’HUB
Categoria: software
Tipologia: componente Home Assistant
Difficoltà di implementazione: bassa
Revisione scheda: 2.3

Il componente “Xiaomi Gateway” di Home Assistant è necessario per integrare il BRIDGE/Gateway ZigBee↔︎TCP/IP della linea Xiaomi Mi Smart Home (Mijia).

Tale gateway ha la funzione BRIDGE/Gateway (in pratica, di accentratore) per tutti i dispositivi ZigBee della linea Xiaomi composta da sensori, interruttori, pulsati, dispositivi ed altro nonché tutti quelli compatibili (per esempio alcuni della linea IKEA TRÅDFRI, oppure alcuni Aqara).

Il nome completo del componente in realtà sarebbe “Xiaomi Gateway (Aqara)“, ma si tratta di un nome estremamente fuorviante. Il componente, infatti, consente SOLO l’integrazione del gateway Xiaomi Mi (Mijia) e NON del gateway LUMI Aqara il quale, sebbene concettualmente molto simile (è anch’esso un BRIDGE/Gateway ZigBee↔︎TCP/IP), non è integrabile.

La presenza del nome “Aqara” fa riferimento al fatto che eventuali componenti (sensori, attuatori ecc.) marchiati Aqara compatibili col gateway Xiaomi, nel momento in cui quest’ultimo viene integrato con Home Assistant vengono a loro volta integrati. Non è vero il contrario: componenti Xiaomi compatibili a un gateway Aqara NON possono essere indirettamente integrati con Home Assistant come sopra, in quanto quest’ultimo NON può essere integrato con Home Assistant.

Il gateway è inizialmente configurato (per l’accesso alla propria Wi-Fi) tramite l’applicazione “Xiaomi Mi Home” (disponibile per Android e iOS) e, una volta effettuata tale configurazione, sempre tramite l’app è possibile collegare ad esso componenti “satellite” a lui connessi tramite protocollo ZigBee. I comportamenti (vale a dire notifiche, allarmi, regolazioni) di tali componenti rispetto al gateway (emissione allarmi sonori, visivi o notifiche verso l’app) sono amministrati e gestiti dal Gateway tramite l’app “Xiaomi Mi Home”.

Una volta configurato il gateway presso la propria Wi-Fi tramite l’app “Xiaomi Mi Home”, sarà possibile integrarlo – tramite il componente “Xiaomi Gateway” qui descritto – con la propria istanza di Home Assistant al fine di:

  • integrare le funzionalità stesse del gateway (emissione effetti sonori, accensione – cromatica – della sua luce LED);
  • integrare i dispositivi/sensori/componenti eventualmente collegati al gateway stesso.
ATTENZIONE: Per effettuare tale integrazione è necessario che la versione del firmware del componente sia uguale o inferiore alla 1.41.159. Firmware superiori non consentono l’integrazione qui descritta, salvo l’attuazione di questa guida.

Una volta effettuata l’integrazione il Gateway e gli eventuali componenti satellite emergeranno su Home Assistant come entità di vario tipo, in base alla loro natura (appunto sensori, pulsanti ecc.).

Dispositivi supportati
  • Gatewa Xiaomi (lumi.gateway.v2, lumi.gateway.v3)
  • LUMI Aqara Air Conditioning Companion (lumi.acpartner.v3)
  • LUMI Aqara Intelligent Door Lock (lock.aq1)
  • Temperature and Humidity Sensor (prima e seconda generazione)
  • Motion Sensor (prima e seconda generazione)
  • Door and Window Sensor (prima e seconda generazione)
  • Button 1st generation (gestibili: pressione singola, doppia, lunga)
  • Button 2nd generation (gestibili: pressione singola, doppia)
  • Plug aka Socket (versione ZigBee: riporta potenza consumata, istantanea, stato e se il dispositivo è in uso)
  • Wall Plug (riporta potenza consumata, istantanea, stato)
  • LUMI Aqara Wall Switch (pressione singola)
  • LUMI Aqara Wall Switch (pressione doppia)
  • LUMI Aqara Wall Switch LN (pressione singola)
  • LUMI Aqara Wall Switch LN (pressione doppia)
  • LUMI Aqara Wireless Switch (pressione singola)
  • LUMI Aqara Wireless Switch (pressione doppia)
  • LUMI/Xiaomi Cube
  • Gas Leak Detector (riporta allarme e densità)
  • Smoke Detector (riporta allarme e densità)
  • Gateway (gestibili: luce, sensore di luminosità, riproduzione suoni)
  • Intelligent Curtain
  • Water Leak Sensor
  • Vibration Sensor
  • Battery
Dispositivi non supportati
  • Gateway LUMI Aqara
  • Gateway Radio
  • Gateway Button
  • Xiaomi Mi Air Conditioning Companion (lumi.acpartner.v2)
  • LUMI Aqara Intelligent Air Conditioner Controller Hub (lumi.acpartner.v1)
  • Decoupled mode of the Aqara Wall Switches (pressione singola e doppia)
  • Additional alarm events of the Gas and Smoke Detector: Analog alarm, battery fault alarm (rilevazione fumi), sensitivity fault alarm, I2C communication failure

N.b. La lista è in continua evoluzione presso la pagina ufficiale del componente.

Guida

La guida di dettaglio all’integrazione è la seguente:

Integrare il Gateway Xiaomi Mi Smart Home a Home Assistant

Configurazione

Il blocco di codice da inserire presso la configurazione di Home Assistant il quale consente di integrare il gateway è il seguente:

xiaomi_aqara:
  discovery_retry: 5
  gateways:
    - key: xxxxxxxxxxxxxxxx

In caso siano presenti più gateway, la sintassi è la seguente:

xiaomi_aqara:
  gateways:
    - mac: xxxxxxxxxxxx
      key: xxxxxxxxxxxxxxxx
    - mac: xxxxxxxxxxxx
      key: xxxxxxxxxxxxxxxx

Le variabili disponibili per la personalizzazione della configurazione sono le seguenti:

interface(stringa, opzionale) – L’interfaccia di rete dalla quale ricercare la presenza del gateway.
discovery_retry(interno, opzionale) – Il numero di volte per le quali Home Assistant ritenta la connessione al gateway in caso di fallimento. Default: 3
gateway(map, richiesto) – L’elenco dei gateway da integrare.

mac(stringa) – Il MAC Address del gateway. Opzionale in caso sia presente un solo gateway.
key(stringa, richiesta) – La chiave di accesso LAN al gateway (spiegato nella guida dedicata all’integrazione del Gateway su Home Assistant).
host(stringa, opzionale) – L’indirizzo IP del gateway. Utilizzato in caso non si voglia utilizzare il multicast discovery automatico.
disable(booleano, opzionale) – Disabilita il gateway. Usato per non integrare un determinato gateway in caso della co-presenza di più gateway.

Servizi

L’integrazione di questo componente prevede quattro servizi:

xiaomi_aqara.play_ringtoneRiproduce uno specifico effetto sonoro
xiaomi_aqara.stop_ringtoneInterrompe la riproduzione di un effetto sonoro
xiaomi_aqara.add_deviceAttiva la modalità di aggiunta dispositivi satellite sul gateway. Equivale a farlo tramite l’app “Mi Home”
xiaomi_aqara.remove_deviceImpone al gateway di rimuovere eventuali dispositivi satellite sul gateway. Equivale a farlo tramite l’app “Mi Home”

Servizio “xiaomi_aqara.play_ringtone”

Se evocato, impone al gateway di riprodurre un suono specifico tra quelli disponibili di fabbrica. Tale servizio funziona solo su gateway con firmware a partire dalla versione 1.4.1_145. Si tratta di una funzione utile, per esempio, come notifica acustica nelle nostre automazioni Home Assistant.

Attributi dati del servizioOpzionaleDescrizione
gw_macnoMAC address del gateway
ringtone_idnoL’ID del suono da riprodurre
ringtone_volyesIl volume in percentuale

Valori accettati per il camporingtone_id sono:

  • Allarmi
    • 0 – Police car 1
    • 1 – Police car 2
    • 2 – Accident
    • 3 – Countdown
    • 4 – Ghost
    • 5 – Sniper rifle
    • 6 – Battle
    • 7 – Air raid
    • 8 – Bark
  • Campanelli
    • 10 – Doorbell
    • 11 – Knock at a door
    • 12 – Amuse
    • 13 – Alarm clock
  • Sveglia
    • 20 – MiMix
    • 21 – Enthusiastic
    • 22 – GuitarClassic
    • 23 – IceWorldPiano
    • 24 – LeisureTime
    • 25 – ChildHood
    • 26 – MorningStreamLiet
    • 27 – MusicBox
    • 28 – Orange
    • 29 – Thinker
  • Suoni personalizzati (aggiunti tramite l’app “Mi Home”) a partire dall’ID 10001, a crescere.

Servizio “xiaomi_aqara.stop_ringtone”

Se evocato, impone al gateway di interrompere la riproduzione di qualsiasi suono in corso di riproduzione.

Attributi dati del servizioOpzionaleDescrizione
gw_macnoMAC address del gateway

Servizio “xiaomi_aqara.add_device”

Se evocato, impone al gateway di attivare la modalità di aggiunta dispositivi satellite sul gateway. Equivale a farlo tramite l’app “Mi Home”

Attributi dati del servizioOpzionaleDescrizione
gw_macnoMAC address del gateway

Servizio “xiaomi_aqara.remove_device”

Se evocato, impone al gateway di rimuovere eventuali dispositivi satellite sul gateway. Equivale a farlo tramite l’app “Mi Home”

Attributi dati del servizioOpzionaleDescrizione
gw_macnoMAC address del gateway
device_id
noIndirizzo Hardware del dispositivo satellite da rimuovere

Esempi d’uso in automazione

Vediamo un esempio:

- alias: Doppio click
  trigger:
    platform: event
    event_type: xiaomi_aqara.click
    event_data:
      entity_id: binary_sensor.switch_158d000xxxxxc2
      click_type: double
  action:
    service: light.toggle
    data:
      entity_id: light.living_room_lamp

In questo esempio, il doppio click di un pulsante Aqara (entità di nome “binary_sensor.switch_158d000xxxxxc2“) integrato tramite Gateway e il presente componente “Xiaomi Gateway (Aqara)” fa sì che si che una lampada (entità di nome “light.living_room_lamp“) si accenda/spenga.

Problemi

Può capitare di trovare sui log di Home Assistant voci di questo tipo:

2017-08-20 16:51:19 ERROR (SyncWorker_0) [homeassistant.components.xiaomi] No gateway discovered
2017-08-20 16:51:20 ERROR (MainThread) [homeassistant.setup] Setup failed for xiaomi: Component failed to initialize.

Questo significa che il gateway non è stato riconosciuto da Home Assistant.

Per tentare di risolvere, appurare i seguenti aspetti:

  • Assicurarsi di aver attivato l’accesso LAN sul gateway (vedi guida all’integrazione su Home Assistant).
  • Disattivare il firewall sul dispositivo dove è in esecuzione Home Assistant.
  • Assicurarsi che il router Wi-Fi supporti (e abbia attivato) il servizio multicast (mDNS).
  • Provare a impostare il campo “mac” vuoto.
  • Provare a impostare il campo “discovery_retry” a 10.
  • Provare a disattivare e riattivare l’accesso LAN sul gateway.
  • Effettuare un hard reset del gateway: premere il suo pulsante per 30 secondi ed effettuare la procedura di pairing sull’app “Xiaomi Mi Home”.
  • In caso Home Assistant sia in esecuzione su Docker, assicurarsi di usare l’impostazione “–net=host” (va aggiunta nel file “/boot/cmdline.txt“).
  • In caso si riceva, in caso di tentativo di controllo della luce del gateway, l’errore{"error":"Invalid key"}, rigenerare la chiave (oggetto della guida all’integrazione su Home Assistant) usando uno smartphone Android (alcune istanze hanno problemi con le chiavi generate da iOS) o, alternativamente, un emulatore come bluestacks.
  • In caso la libreria richiesta “PyXiaomiGateway” non possa essere installata, andranno installate prima alcune dipendenze necessarie comepython3-dev,libssl-dev,libffi-dev in modo manuale (e.g., $ sudo apt-get install python3-dev libssl-dev libffi-dev).


Home Assistant Official LogoATTENZIONE: 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.