Piattaforma Home Assistant “MQTT Vacuum” (aspirapolvere MQTT)

6 minuti di lettura
Produttore: Home Assistant Community
Disponibilità: incluso nell’HUB personale Home Assistant
Categoria: software
Tipologia: piattaforma Home Assistant
Famiglia: componente “Vacuum” Home Assistant
Difficoltà di implementazione: media

La piattaforma “MQTT Vacuum” (robot aspirapolvere), figlia del componente “Vacuum”, serve per definire delle entità di controllo utili, appunto, a gestire tramite Home Assistant dei robot per la pulizia domestica che prevedano di essere controllati tramite protocollo MQTT.

I dispositivi gestibili tramite la piattaforma MQTT Vacuum possono essere diversi.
Ad esempio:

  • robot aspirapolvere Wi-Fi che supportino nativamente MQTT;
  • un’interfaccia software (eg. Node-RED) che si frapponga tra la piattaforma MQTT HVAC di Home Assistant e un qualunque oggetto a valle, controllabile in modo diverso.

Il primo caso è il più facile da capire. La configurazione della piattaforma invia comandi MQTT e riceve telemetrie MQTT direttamente dal dispositivo controllato. Facile.

Il secondo caso è quello più sofisticato: ciò con cui questa piattaforma “parla” (sempre inconsapevolmente) non è più un dispositivo ma con un software il quale sappia interpretare i comandi MQTT emessi da Home Assistant tramite la piattaforma MQTT HVAC e li traduca in qualcos’altro.

Questo “qualcos’altro” può essere qualunque cosa. Portando il caso di Node-RED, si potrebbe estremizzare il concetto immaginando un flusso di nodi che, intercettato il comando di accensione ricevuto via MQTT, provveda a inviare un SMS al telefono di una persona con scritto “Accendi il robot!” –  “Spegni il robot!“. Potrebbe sembrare un’ipotesi peregrina, ma non lo è. Visti i centinaia di nodi di output disponibili per questo potente software, nel campo reale si potrebbero utilizzare tecniche diverse per arrivare a domotizzare qualcosa che non lo sarebbe. Tipicamente, questo “qualcos’altro” potrebbe essere l’invio di segnali infrarossi catturati precedentemente dal telecomando originale del robot aspirapolvere.

N.b. Per utilizzare questa piattaforma è necessario che il componente “MQTT” di Home Assistant sia stato preventivamente configurato (vedi prima parte della scheda dedicata al componente “MQTT”). Si consiglia inoltre di leggere con attenzione la guida dedicata al tema della configurazione dei componenti MQTT nella propria domotica.

A prescindere, si consiglia di affrontare l’implementazione di questa piattaforma solo in presenza di almeno una competenza base sul tema MQTT.

Configurazione

Per creare un’entità aspirapolvere tramite questa piattaforma il blocco da inserire presso la configurazione “configuration.yaml” di Home Assistant è di base analoga alla seguente:

# Esempio di configurazione 
vacuum:
  - platform: mqtt

La personalizzazione della piattaforma prevede due approcci: “legacy” o “state”. La “legacy” è un set di parametri presenti nella prima versione della piattaforma, la quale è stata superata dalla nuova, la “state”. A seguire riportiamo solo la descrizione e spiegazione dei campi relativi alla più recente “state”, per quanto l’elenco completo dei parametri “legacy” siano comunque disponibili sulla pagina presente sul sito di Home Assistant.

<tr”>availability_topic(Stringa, opzionale) Il topic MQTT al quale iscriversi per ottenere lo stato online/offline da parte del dispositivo controllato. Solitamente si indica il topic LWT.

ParametroDescrizione
name(Stringa, opzionale) Descrive il nome dell’entità di tipo Vacuum.
schema(Stringa, opzionale) Descrive l’adozione dello schema “legacy”o “state” spiegato poco sopra. Di default, se non indicata, viene applicata “legacy“.
supported_features(Lista, opzionale) Elenca le feature presenti nel dispositivo da controllare. I valori possibili sono: rt, stop, pause, return_home, battery, status, locate, clean_spot, fan_speed, send_command). Se non indicate, le feature considerate disponibili sono: start, stop, return_home, status, battery, clean_spot.
command_topic(Stringa, opzionale) Il topic MQTT da far pubblicare a Home Assistant al fine di controllare il robot.
qos(Intero, opzionale) Il valore di quality-of-service per la pubblicazione dei topic MQTT. Default: 0 (Cos’è QoS?)
retain(Booleano, opzionale) Se attivare o meno la retain dei messaggi MQTT. Default: false
payload_start(Stringa, opzionale) Il payload da inviare assieme al comando indicato in command_topic al fine di avviare il ciclo di pulizia.
payload_stop(Stringa, opzionale) Il payload da inviare assieme al comando indicato in command_topic al fine di interrompere il ciclo di pulizia.
payload_pause(Stringa, opzionale) Il payload da inviare assieme al comando indicato in command_topic al fine di interrompere temporaneamente il ciclo di pulizia.
state_topic(Stringa, opzionale) Il topic MQTT al quale iscriversi per ottenere i cambi di stato operativo da parte del dispositivo controllato.
payload_return_to_base(Stringa, opzionale) Il payload da inviare assieme al comando indicato in command_topic al fine di avviare comandare al robot il rientro alla base di ricarica.
payload_clean_spot(Stringa, opzionale) Il payload da inviare assieme al comando indicato in command_topic al fine di avviare il ciclo di pulizia in un punto preciso predefinito.
payload_locate(Stringa, opzionale) Il payload da inviare assieme al comando indicato in command_topic al fine di localizzare il robot.
set_fan_speed_topic(Stringa, opzionale) Il topic MQTT da far pubblicare a Home Assistant al fine di controllare la velocità di aspirazione dell’aspirapolvere.
fan_speed_list(Lista, opzionale) Lista di velocità previste.
send_command_topic(Stringa, opzionale) Il topic MQTT da far pubblicare a Home Assistant al fine di inviare comandi personalizzati al robot.
payload_available(Stringa, opzionale) – Il payload che rappresenta lo stato “disponibile” da parte del dispositivo controllato. Esempio: “online”. Viene usato in abbinamento alla variabile “availability_topic“. Solitamente si indica il payload LWT.
payload_not_available(Stringa, opzionale) – Il payload che rappresenta lo stato “non disponibile” da parte del dispositivo controllato. Esempio: “offline”. Viene usato in abbinamento alla variabile “availability_topic“. Solitamente si indica il payload LWT.
json_attribues_topic(Stringa, opzionale) Il topic MQTT da sottoscrivere per ricevere un payload JSON e impostare un relativo sensore.
OPTIMISTIC MODE

Se una proprietà lavora in “optimistic mode” (ovvero quando il corrispondente “state_topic” non è impostato, Home Assistant assume che ogni variazione di stato dell’entità attuata dall’utente – e quindi la corrispondente pubblicazione MQTT di topic e payload relativi alla variazione stessa – abbia avuto esito positivo presso il dispositivo controllato, pertanto lo stato dell’entità presso Home Assistant assumerà automaticamente ed immediatamente il nuovo stato.

In caso invece lo “state topic” sia stato definito, il cambiamento di stato dell’entità non viene modificato fin tanto che tale topic e relativo payload non siano stati ricevuti.

USO DI TEMPLATE

In ogni “*_state_topic” può essere definito un template per l’estrazione (parsing) del dato di stato. Può anche esserne definito uno per tutti, utilizzando la proprietà “value_template“. Questo si traduce in una grande comodità sopratutto quando si è in presenza di payload scritti in notazione JSON.

CONFIGURAZIONE COMPLETA

Un esempio di configurazione “tipo” per un robot compatibile col protocollo MQTT è la seguente:

# Esempio di configurazione
vacuum:
  - platform: mqtt
    name: "MQTT Vacuum"
    schema: state
    supported_features:
      - start
      - pause
      - stop
      - return_home
      - battery
      - status
      - locate
      - clean_spot
      - fan_speed
      - send_command
    command_topic: "vacuum/command"
    state_topic: "vacuum/state"
    set_fan_speed_topic: "vacuum/set_fan_speed"
    fan_speed_list:
      - min
      - medium
      - high
      - max
    send_command_topic: 'vacuum/send_command'

Protocollo MQTT

Vediamo, sfruttando l’esempio della configurazione di cui sopra, quali siano i topic MQTT che influenzano il comportamento del dispositivo e dell’entità creata presso Home Assistant.

COMANDO

Topic indicato nell’esempio: vacuum/command

In base alla definizione del campo “command_topic” Home Assistant provvederà  – quando comandato di farlo tramite interfaccia o automazioni – a pubblicare sul broker MQTT tale topic unitamente a uno dei possibili payload:

  • start – avvio pulizia
  • pause – interruzione temporanea della pulizia
  • return_to_base – ritorno alla base di ricarica
  • stop – interruzione della pulizia
  • clean_spot – avvio pulizia su un punto predeterminato della casa
  • locate – localizza il robot (solitamente tramite riproduzione da parte sua di un suono)

Quando – per esempio – l’entità “Vacuum” verrà comandata all’accensione, verrà pubblicato da Home Assistant sul broker MQTT un topic come quello che segue:

vacuum/command start

COMANDO PERSONALIZZATO

È anche possibile, tramite la configurazione del campo “send_command_topic” e il servizio “vacuum.send_command“, inviare comandi personalizzati.

Tale servizio accetta tre parametri:

  • entity_id
  • command
  • params (opzionale)

Se non vengono forniti params (parametri del comando personalizzato), il comando viene inviato come payload del topic indicato nel campo “command_topic“. Se invece sono forniti, il servizio li invia come payload JSON così strutturato:

{
  'command': 'command',
  'param1-key': 'param1-value'
}

Un esempio di automazione:

automation:
- alias: Push command based on sensor
    trigger:
      - platform: state
        entity_id: sensor.sensor
    action:
      service: vacuum.send_command
      data:
        entity_id: 'vacuum.vacuum_entity'
        command: 'custom_command'
        params:
          - key: value
RICEZIONE STATO

Topic telemetrico previsto nel caso dell’esempio: vacuum/status

Se non configurato in modalità “optimistic“, Home Assistant assume che i comandi siano andati a buon fine. Se invece il parametro “state_topic” è configurato, il topic telemetrico MQTT indicato sarà quello al quale Home Assistant si iscriverà per ottenere i cambi di stato da parte del robot. Senza ricezione di quel topic unitamente a un payload, Home Assistant non prenderà per buoni i comandi eseguiti tramite l’entità “Vacuum”.

Il payload può contenere fino a tre elementi:

  • state
  • battery_level
  • fan_speed

Lo “state” prevede i seguenti stati:

  • cleaning,
  • docked,
  • paused,
  • idle,
  • returning,
  • error

Esempio di telemetria:

vacuum/stat { “battery_level”: 61, “state”: “docked”, “fan_speed”: “off” }

Impostazione stato livello di aspirazione

Topic previsto nel caso dell’esempio: vacuum/set_fan_speed

Se il campo “set_fan_speed_topic” è impostato, il topic MQTT indicato verrà pubblicato da Home Assistant ogni qual volta verrà variata (da interfaccia o tramite automazioni) presso l’entità “Vacuum” la velocità di aspirazione del robot.

I payload associabili sono:

  • min
  • medium
  • high
  • max

I quali permettono di regolare a varie velocità la suzione.

Quando – per esempio – l’entità “Vacuum” verrà comandata alla regolazione di massima forza di aspirazione, verrà pubblicato da Home Assistant sul broker MQTT un topic come quello che segue:

vacuum/set_fan_speet max


Domotizzare un robot aspirapolvere non-domotico con Broadlink e Home Assistant


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.


Please comment below