MQTT Vacuum


The mqtt vacuum component allows you to control your MQTT-enabled vacuum.

Configuration

To add your MQTT vacuum to your installation, add the following to your configuration.yaml file:

# Example configuration.yaml entry
vacuum:
  - platform: mqtt
    name: "MQTT Vacuum"
    supported_features:
      - turn_on
      - turn_off
      - pause
      - stop
      - return_home
      - battery
      - status
      - locate
      - clean_spot
      - fan_speed
      - send_command
    command_topic: "vacuum/command"
    battery_level_topic: "vacuum/state"
    battery_level_template: ""
    charging_topic: "vacuum/state"
    charging_template: ""
    cleaning_topic: "vacuum/state"
    cleaning_template: ""
    docked_topic: "vacuum/state"
    docked_template: ""
    error_topic: "vacuum/state"
    error_template: ""
    fan_speed_topic: "vacuum/state"
    fan_speed_template: ""
    set_fan_speed_topic: "vacuum/set_fan_speed"
    fan_speed_list:
      - min
      - medium
      - high
      - max
    send_command_topic: 'vacuum/send_command'

Configuration Variables

name

(string)(Optional)The name of the vacuum.

Default value: MQTT Vacuum

supported_features

(string list)(Optional)List of features that the vacuum supports (possible values are turn_on, turn_off, pause, stop, return_home, battery, status, locate, clean_spot, fan_speed, send_command).

Default value: turn_on, turn_off, stop, return_home, status, battery, clean_spot

command_topic

(string)(Optional)The MQTT topic to publish commands to control the vacuum.

qos

(integer)(Optional)The maximum QoS level of the state topic.

Default value: 0

retain

(boolean)(Optional)If the published message should have the retain flag on or not.

Default value: false

payload_turn_on

(string)(Optional)The payload to send to the command_topic to begin the cleaning cycle.

Default value: turn_on

payload_turn_off

(string)(Optional)The payload to send to the command_topic to turn the vacuum off.

Default value: turn_off

payload_return_to_base

(string)(Optional)The payload to send to the command_topic to tell the vacuum to return to base.

Default value: return_to_base

payload_stop

(string)(Optional)The payload to send to the command_topic to stop the vacuum.

Default value: stop

payload_clean_spot

(string)(Optional)The payload to send to the command_topic to begin a spot cleaning cycle.

Default value: clean_spot

payload_locate

(string)(Optional)The payload to send to the command_topic to locate the vacuum (typically plays a song).

Default value: locate

payload_start_pause

(string)(Optional)The payload to send to the command_topic to start or pause the vacuum.

Default value: start_pause

battery_level_topic

(string)(Optional)The MQTT topic subscribed to receive battery level values from the vacuum.

battery_level_template

(string)(Optional)Defines a template to define the battery level of the vacuum.

charging_topic

(string)(Optional)The MQTT topic subscribed to receive charging state values from the vacuum.

charging_template

(string)(Optional)Defines a template to define the charging state of the vacuum.

cleaning_topic

(string)(Optional)The MQTT topic subscribed to receive cleaning state values from the vacuum.

cleaning_template

(string)(Optional)Defines a template to define the cleaning state of the vacuum.

docked_topic

(string)(Optional)The MQTT topic subscribed to receive docked state values from the vacuum.

docked_template

(string)(Optional)Defines a template to define the docked state of the vacuum.

error_topic

(string)(Optional)The MQTT topic subscribed to receive error messages from the vacuum.

error_template

(string)(Optional)Defines a template to define potential error messages emitted by the vacuum.

fan_speed_topic

(string)(Optional)The MQTT topic subscribed to receive fan speed values from the vacuum.

fan_speed_template

(string)(Optional)Defines a template to define the fan speed of the vacuum.

set_fan_speed_topic

(string)(Optional)The MQTT topic to publish commands to control the vacuum’s fan speed.

fan_speed_list

(string list)(Optional)List of possible fan speeds for the vacuum.

send_command_topic

(string)(Optional)The MQTT topic to publish custom commands to the vacuum.

availability_topic

(string)(Optional)The MQTT topic subscribed to receive availability (online/offline) updates.

payload_available

(string)(Optional)The payload that represents the available state.

Default value: online

payload_not_available

(string)(Optional)The payload that represents the unavailable state.

Default value: offline

Default MQTT Protocol

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

Basic Commands

MQTT topic: vacuum/command

Possible MQTT payloads:

  • turn_on - Begin cleaning
  • turn_off - Turn the Vacuum off
  • 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)
  • start_pause - Toggle the vacuum between cleaning and stopping

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

Send Custom Command

MQTT topic: vacuum/send_command

MQTT payload for send_command can be an arbitrary value handled by the vacuum’s MQTT-enabled firmware.

Status/Sensor Updates

MQTT topic: vacuum/state

MQTT payload:

{
    "battery_level": 61,
    "docked": true,
    "cleaning": false,
    "charging": true,
    "fan_speed": "off",
    "error": "Error message"
}

Retrofitting a non-wifi vacuums

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