Platform Home Assistant "MQTT Vacuum" (MQTT vacuum cleaner)

6 minutes of reading
Proconductor: Home Assistant Community
Availability: included in thepersonale HUB Home Assistant
Category: software
Type: platform Home Assistant
Family: "Vacuum" component Home Assistant
Implementation difficulties: half

The "MQTT Vacuum" platform (robot vacuum cleaner), daughter of the "Vacuum" component, serves to define of the entity control useful, appanointed, to manage through Home Assistant of home cleaning robot that they expect to be controlled by proProtocol MQTT.

Devices that can be managed through the platform MQTT Vacuum may be different.
For example:

  • robot vacuum cleaner Wi-Fi which natively support MQTT;
  • a software interface (Eg. Node-RED) That yes frapponga between the MQTT HVAC platform of Home Assistant and any object downstream, controllable differently.

The first case it is the easiest to understand. The platform configuration sends MQTT commands and receives MQTT telemetry directly from the controlled device. Easy.

The second case it is the most sophisticated: what this platform "speaks" (always unconsciously) is no longer a device but with a software which sappia interpret the MQTT commands issued by Home Assistant via the MQTT HVAC platform and translate them into something else.

This "something else"Can be anything. Bringing the case to Node-RED, we could take the concept to extremes by imagining a flow of nodes that, intercepted the ignition command received via MQTT, prosend a text message to a person with the message "Turn on the robot!"-"Turn off the robot!". It might seem like a peregrine hypothesis, but it is not. Visas i hundreds of output nodes available for this powerful software, in the real field different techniques could be used to arrive to domotize something that would not be. Typically, this "something else”Could be sending infrared signals previously captured by the original robot vacuum cleaner remote control.

Nb To use this platform it is necessary that the "MQTT" component of Home Assistant has been previously configured (see first part of the card dedicated to the "MQTT" component). We also recommend to read carefully the guide dedicated to the theme of configuration of the MQTT components in the profirst home automation.

Regardless, it is advisable to approach the implementation of this platform alone in the presence of at least one competence basis on the topic MQTT.

Configuration

To create aentity vacuum cleaner through this platform the block to be inserted at the configuration "configuration.yaml" di Home Assistant it is basically similar to the following:

# Esempio di configurazione 
vacuum:
  - platform: mqtt

The customization of the platform includes two approcci: "legacy" or "state". The "legacy" is a set of parameters present in the first version of the platform, which was superseded by the new one, the "state". Below is only the description and explanation of the fields relating to the most recent "state", although the complete list of "legacy" parameters is still available on the page on the site of Home Assistant.

<Tr ">availability_topic(String, optional) The MQTT topic to which to register to get the status online / offline by the controlled device. Usually the topic is indicated LWT.

ParameterDescription
name(String, optional) Describes the name of the Vacuum type entity.
schema(String, optional) Describes the adoption of the "legacy" or "state" scheme explained above. By default, if not indicated, it comes applicata "legacy"
supported_features(List, optional) Lists the features present in the device to be controlled. The possible values ​​are: rt, stop, pause, return_home, battery, status, locate, clean_spot, fan_speed, send_command). If not indicated, the features considered available are: start, stop, return_home, status, battery, clean_spot.
command_topic(String, optional) The MQTT topic to be published to Home Assistant in order to control the robot.
qos(Integer, optional) The quality-of-service value for publishing MQTT topics. Default: 0 (What is QoS?)
retain(Boolean, optional) Whether to enable or not the retain of MQTT messages. Default: false
payload_start(String, optional) The payload to be sent together with the command indicated in command_topic in order to start the cleaning cycle.
payload_stop(String, optional) The payload to be sent together with the command indicated in command_topic in order to interrupt the cleaning cycle.
payload_pause(String, optional) The payload to be sent together with the command indicated in command_topic in order to temporarily interrupt the cleaning cycle.
state_topic(String, optional) The MQTT topic to which to register to get the operational status changes by the controlled device.
payload_return_to_base(String, optional) The payload to be sent together with the command indicated in command_topic in order to start, command the robot to return to the charging base.
payload_clean_spot(String, optional) The payload to be sent together with the command indicated in command_topic in order to start the cleaning cycle at a specific pre-defined point.
payload_locate(String, optional) The payload to be sent together with the command indicated in command_topic in order to locate the robot.
set_fan_speed_topic(String, optional) The MQTT topic to be published to Home Assistant in order to control the suction speed of the vacuum cleaner.
fan_speed_list(List, optional) List of expected speeds.
send_command_topic(String, optional) The MQTT topic to be published to Home Assistant in order to send custom commands to the robot.
payload_available(String, optional) - The payload that rappit returns the "available" status of the controlled device. Example: "online". It is used in abbinameto the variable "availability_topic". Usually the payload is indicated LWT.
payload_not_available(String, optional) - The payload that rappit returns the status "not available" by the controlled device. Example: "offline". It is used in abbinameto the variable "availability_topic". Usually the payload is indicated LWT.
json_attribues_topic(String, optional) The MQTT topic to subscribe to receive a JSON payload and set a relative sensor.
OPTIMISTIC MODE

If one proproperty works in "optimistic mode" (ie when the correspondent "state_topic"Is not set, Home Assistant takes that any change in status of theentity implemented by the user - and therefore the corresponding MQTT publication of topics and payloads related to the variation itself - has been successful at the controlled device, therefore the status of the entity at Home Assistant will take over automatically and immediately the new state.

If instead the "state topic" has been defined, the change in status of the entity it is not changed as long as this topic is relative payload have not been received.

USE OF TEMPLATES

In each "* _state_topic”Can be defined as a template for the extraction (parsing) of the status data. It can also be defined one for all, using the proproperty "value_template". This translates into a great comfort especially when there are payloads written in JSON notation.

COMPLETE CONFIGURATION

An example of a "type" configuration for a robot compatible with proMQTT tocollo is the following:

# 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'

ProMQTT tocollo

Let's see, using the example of the above configuration, what are the MQTT topics that influence the behavior of the device and the entity created at Home Assistant.

COMMAND

Topic indicated in the example: vacuum / command

Based on the field definition "command_topic” Home Assistant prowill see - when commanded to do so via interface or automations - to publish this topic together with one of the possible payloads on the broker MQTT:

  • start - start cleaning
  • pause - temporary interruption of cleaning
  • return_to_base - return to the charging station
  • stop - interruption of cleaning
  • clean_spot - start cleaning on a predetermined point of the house
  • locate - locates the robot (usually via riproits part of a sound)

When - for example - the "Vacuum" entity will be commanded at power up, it will be published by Home Assistant on the broker MQTT a topic like the one below:

vacuum / command start

CUSTOMIZED COMMAND

It is also possible, through the configuration of the field "send_command_topic"And the service"vacuum.send_command", Send custom commands.

This service accepts three parameters:

  • entity_id
  • command
  • params (Optional)

If not supplied params (parameters of the custom command), the command is sent as a payload of the topic indicated in the field "command_topic". If they are provided, the service sends them as a structured JSON payload:

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

An example of automation:

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
RECEIVING STATUS

Telemetric topic expected in the case of the example: vacuum / status

If not configured in "optimistic", Home Assistant assumes that the commands have been successful. If instead the parameter "state_topic"Is configured, the indicated MQTT telemetry topic will be the one to which Home Assistant will register to get status changes from the robot. Without receiving that topic together with a payload, Home Assistant it will not take good the commands executed through the "Vacuum" entity.

The payload can contain up to three elements:

  • state
  • battery_level
  • fan_speed

The "state" includes the following states:

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

Telemetry example:

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

Setting the suction level status

Expected topic in the case of the example: vacuum / set_fan_speed

If the field "set_fan_speed_topic"Is set, the indicated MQTT topic will be published by Home Assistant whenever the robot suction speed is changed (from interface or through automation) to the "Vacuum" entity.

The payloads that can be associated are:

  • min
  • medium
  • high
  • max

Which allow you to adjust the suction at various speeds.

When - for example - the "Vacuum" entity will be commanded to the maximum suction force adjustment, it will be published by Home Assistant on the broker MQTT a topic like the one below:

vacuum / set_fan_speet max


Home automation of a non-domotic robot vacuum cleaner with Broadlink e Home Assistant


Home Assistant Official LogoATTENZIONE: remember that there is on our FORUM community an ad hoc section dedicated to Home Assistant, for any doubt, question, information on the specific merit of these components.


Please comment below