Componente Home Assistant “Xiaomi Gateway (Aqara – Mijia)”

Produttore: Home Assistant Community
Disponibilità: incluso nell’HUB personale Home Assistant
Categoria: software
Tipologia: componente Home Assistant
Difficoltà di implementazione: medio/bassa

Il componente “Xiaomi Gateway (Aqara – Miija)” di Home Assistant è necessario per integrare il Gateway della linea Xiaomi Smart Home.

Tale Gateway ha la funzione di accentratore per tutti i dispositivi della linea prodotti Xiaomi Smart Home, composta da sensori, interruttori, pulsati, dispositivi ed altro ancora. Il riferimento al nome “Aqara – Mijija” è dato dal fatto che anche i dispositivi Aqara/Mijia (a partire dal gateway fino ai sensori/attuatori ecc.) sono integrabili su Home Assistant con tale componente.

Tale Gateway è inizialmente configurato (per l’ingresso nella 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” (come per esempio un sensore di allagamento, un sensore di rilevazione fumi o altro) connessi tramite protocollo ZigBee.Xiaomi Gateway

I comportamenti (vale a dire notifiche, allarmi e altro) 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 “Mi Home”, sarà possibile integrarlo – tramite il componente Xiaomi Gateway (Aqara – Mijia) 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 integrati con il Gateway stesso.

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
  • Xiaomi Gateway (sia Mi Home Mijia che Aqara) (lumi.gateway.v2, lumi.gateway.v3)
  • Aqara Air Conditioning Companion (lumi.acpartner.v3)
  • 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)
  • Aqara Wall Switch (pressione singola)
  • Aqara Wall Switch (pressione doppia)
  • Aqara Wall Switch LN (pressione singola)
  • Aqara Wall Switch LN (pressione doppia)
  • Aqara Wireless Switch (pressione singola)
  • Aqara Wireless Switch (pressione doppia)
  • 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 Radio
  • Gateway Button
  • Xiaomi Mi Air Conditioning Companion (lumi.acpartner.v2)
  • 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.

Configurazione

Il blocco, presso configuration.yaml, che definisce la piattaforma è questo:

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 da quale ricercare la presentaa 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 di connessione

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 (oggetto della 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.
  • 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“.
  • 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.