home-assistant.io/source/_integrations/vacuum.mqtt.markdown

title	description	ha_category	ha_release	ha_domain
MQTT Vacuum	Instructions on how to integrate your MQTT enabled Vacuum within Home Assistant.	Vacuum	0.54	mqtt

The mqtt vacuum {% term integration %} allows you to control your MQTT-enabled vacuum. The initial state of the MQTT vacuum {% term entity %} will set to unknown and can be reset by a device by sending a null payload as state.

Configuration

MQTT vacuum configuration section.

{% configuration %} availability: description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with availability_topic. required: false type: list keys: payload_available: description: The payload that represents the available state. required: false type: string default: online payload_not_available: description: The payload that represents the unavailable state. required: false type: string default: offline topic: description: An MQTT topic subscribed to receive availability (online/offline) updates. required: true type: string value_template: description: "Defines a template to extract device's availability from the topic. To determine the devices's availability result of this template will be compared to payload_available and payload_not_available." required: false type: template availability_mode: description: When availability is configured, this controls the conditions needed to set the entity to available. Valid entries are all, any, and latest. If set to all, payload_available must be received on all configured availability topics before the entity is marked as online. If set to any, payload_available must be received on at least one configured availability topic before the entity is marked as online. If set to latest, the last payload_available or payload_not_available received on any configured availability topic controls the availability. required: false type: string default: latest availability_template: description: "Defines a template to extract device's availability from the availability_topic. To determine the devices's availability result of this template will be compared to payload_available and payload_not_available." required: false type: template availability_topic: description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with availability. required: false type: string command_topic: description: The MQTT topic to publish commands to control the vacuum. required: false type: string device: description: "Information about the device this switch is a part of to tie it into the device registry. Only works when unique_id is set. At least one of identifiers or connections must be present to identify the device." required: false type: map keys: configuration_url: description: 'A link to the webpage that can manage the configuration of this device. Can be either an http://, https:// or an internal homeassistant:// URL.' required: false type: string connections: description: 'A list of connections of the device to the outside world as a list of tuples [connection_type, connection_identifier]. For example the MAC address of a network interface: "connections": [["mac", "02:5b:26:a8:dc:12"]].' required: false type: list hw_version: description: The hardware version of the device. required: false type: string identifiers: description: A list of IDs that uniquely identify the device. For example a serial number. required: false type: [string, list] manufacturer: description: The manufacturer of the device. required: false type: string model: description: The model of the device. required: false type: string model_id: description: The model identifier of the device. required: false type: string name: description: The name of the device. required: false type: string serial_number: description: "The serial number of the device." required: false type: string suggested_area: description: 'Suggest an area if the device isn’t in one yet.' required: false type: string sw_version: description: The firmware version of the device. required: false type: string via_device: description: 'Identifier of a device that routes messages between this device and Home Assistant. Examples of such devices are hubs, or parent devices of a sub-device. This is used to show device topology in Home Assistant.' required: false type: string encoding: description: The encoding of the payloads received and published messages. Set to "" to disable decoding of incoming payload. required: false type: string default: "utf-8" fan_speed_list: description: List of possible fan speeds for the vacuum. required: false type: [string, list] json_attributes_template: description: "Defines a template to extract the JSON dictionary from messages received on the json_attributes_topic. Usage example can be found in MQTT sensor documentation." required: false type: template json_attributes_topic: description: The MQTT topic subscribed to receive a JSON dictionary payload and then set as sensor attributes. Usage example can be found in MQTT sensor documentation. required: false type: string name: description: The name of the vacuum. Can be set to null if only the device name is relevant. required: false type: string default: MQTT Vacuum object_id: description: Used instead of name for automatic generation of entity_id required: false type: string payload_available: description: The payload that represents the available state. required: false type: string default: online payload_clean_spot: description: The payload to send to the command_topic to begin a spot cleaning cycle. required: false type: string default: clean_spot payload_locate: description: The payload to send to the command_topic to locate the vacuum (typically plays a song). required: false type: string default: locate payload_not_available: description: The payload that represents the unavailable state. required: false type: string default: offline payload_pause: description: The payload to send to the command_topic to pause the vacuum. required: false type: string default: pause payload_return_to_base: description: The payload to send to the command_topic to tell the vacuum to return to base. required: false type: string default: return_to_base payload_start: description: "The payload to send to the command_topic to begin the cleaning cycle." required: false type: string default: start payload_stop: description: "The payload to send to the command_topic to stop cleaning." required: false type: string default: stop platform: description: Must be vacuum. Only allowed and required in MQTT auto discovery device messages. required: true type: string qos: description: The maximum QoS level to be used when receiving and publishing messages. required: false type: integer default: 0 retain: description: If the published message should have the retain flag on or not. required: false type: boolean default: false send_command_topic: description: The MQTT topic to publish custom commands to the vacuum. required: false type: string set_fan_speed_topic: description: The MQTT topic to publish commands to control the vacuum's fan speed. required: false type: string state_topic: description: "The MQTT topic subscribed to receive state messages from the vacuum. Messages received on the state_topic must be a valid JSON dictionary, with a mandatory state key and optionally battery_level and fan_speed keys as shown in the example." required: false type: string supported_features: description: "List of features that the vacuum supports (possible values are start, stop, pause, return_home, battery, status, locate, clean_spot, fan_speed, send_command)." required: false type: [string, list] default: "start, stop, return_home, status, battery, clean_spot" unique_id: description: An ID that uniquely identifies this vacuum. If two vacuums have the same unique ID, Home Assistant will raise an exception. Required when used with device-based discovery. required: false type: string {% endconfiguration %}

Configuration example

# Example configuration.yaml entry
mqtt:
  - vacuum:
      name: "MQTT Vacuum"
      supported_features:
        - start
        - pause
        - stop
        - return_home
        - battery
        - status
        - locate
        - clean_spot
        - fan_speed
        - send_command
      command_topic: "vacuum/command"
      set_fan_speed_topic: "vacuum/set_fan_speed"
      fan_speed_list:
        - min
        - medium
        - high
        - max
      send_command_topic: "vacuum/send_command"

MQTT Protocol

The configuration for this integration expects an MQTT protocol like the following.

Basic Commands

MQTT topic: vacuum/command

Possible MQTT payloads:

• start - Start cleaning
• pause - Pause cleaning
• return_to_base - Return to base/dock
• stop - Stop the vacuum.
• clean_spot - Initialize a spot cleaning cycle
• locate - Locate the vacuum (typically by playing a song)

Send custom command

Vacuum send_command allows three parameters:

• entity_id
• command
• params - optional

If params are not provided it sends command as payload to MQTT send_command topic. If params are provided service sends JSON as payload with such structure:

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

Action trigger example:

- alias: "Push command based on sensor"
    triggers:
      - trigger: state
        entity_id: sensor.sensor
    actions:
      - action: vacuum.send_command
        target:
          entity_id: vacuum.vacuum_entity
        data:
          command: "custom_command"
          params:
            - key: value

MQTT topic: vacuum/send_command

Status/Sensor Updates

MQTT topic: vacuum/state

MQTT payload:

{
    "battery_level": 61,
    "state": "docked",
    "fan_speed": "off"
}

State has to be one of vacuum states supported by Home Assistant:

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

Set Fan Speed

MQTT topic: vacuum/set_fan_speed

Possible MQTT payloads:

• min - Minimum fan speed
• medium - Medium fan speed
• high - High fan speed
• max - Max fan speed

Usage examples

Usage with cloudless Xiaomi vacuums

This integration is supported by the cloud-free Xiaomi Vacuum Webinterface Valetudo.

Retrofitting non-wifi vacuums

• Retrofitting your old Roomba with an ESP8266. This repository provides MQTT client firmware.
• If you own a non-wifi Neato, you can refer to this repository that uses a Raspberry Pi to retrofit an old Neato.