--- title: "MQTT Vacuum" description: "Instructions on how to integrate your MQTT enabled Vacuum within Home Assistant." ha_category: - Vacuum ha_release: 0.54 ha_domain: 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](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) 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](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) 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](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#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 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](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the JSON dictionary from messages received on the `json_attributes_topic`. Usage example can be found in [MQTT sensor](/integrations/sensor.mqtt/#json-attributes-template-configuration) 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](/integrations/sensor.mqtt/#json-attributes-topic-configuration) 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 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](#configuration-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: false type: string {% endconfiguration %} ## Configuration example ```yaml # Example configuration.yaml entry mqtt: - vacuum: 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" ``` ## 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: ```json { 'command': 'command', 'param1-key': 'param1-value' } ``` Service trigger example: ```yaml - alias: "Push command based on sensor" trigger: - platform: state entity_id: sensor.sensor action: service: 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: ```json { "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](https://github.com/Hypfer/Valetudo). ### Retrofitting non-wifi vacuums - Retrofitting your old Roomba with an ESP8266. [This repository](https://github.com/johnboiles/esp-roomba-mqtt) provides MQTT client firmware. - If you own a non-wifi Neato, you can refer to [this repository](https://github.com/jeroenterheerdt/neato-serial) that uses a Raspberry Pi to retrofit an old Neato.