diff --git a/source/_components/vacuum.mqtt.markdown b/source/_components/vacuum.mqtt.markdown new file mode 100644 index 00000000000..c8b45ff6119 --- /dev/null +++ b/source/_components/vacuum.mqtt.markdown @@ -0,0 +1,137 @@ +--- +layout: page +title: "MQTT" +description: "Instructions how to integrate your MQTT enabled Vacuum within Home Assistant." +date: 2017-09-11 20:26 +sidebar: true +comments: false +sharing: true +footer: true +logo: mqtt.png +ha_category: Vacuum +ha_release: 0.54 +--- + +The `mqtt` component allows you to control your MQTT-enabled vacuum. + +To add your MQTT vacuum to your installation, add the following to your `configuration.yaml` file: + +```yaml +# 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: "{{ value_json.battery_level }}" + charging_topic: "vacuum/state" + charging_template: "{{ value_json.charging }}" + cleaning_topic: "vacuum/state" + cleaning_template: "{{ value_json.cleaning }}" + docked_topic: "vacuum/state" + docked_template: "{{ value_json.docked }}" + fan_speed_topic: "vacuum/state" + fan_speed_template: "{{ value_json.fan_speed }}" + set_fan_speed_topic: "vacuum/set_fan_speed" + fan_speed_list: + - min + - medium + - high + - max + send_command_topic: 'vacuum/send_command' +``` + +Basic Configuration variables: + +- **name** (*Optional*): The name of the vacuum. Defaults to `MQTT Vacuum`. +- **supported_features** (*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`). Defaults to `turn_on`, `turn_off`, `stop`, `return_home`, `status`, `battery`, `clean_spot`. +- **command_topic** (*Optional*): The MQTT topic to publish commands to control the vacuum. + +Advanced Configuration variables: + +- **qos** (*Optional*): The maximum QoS level of the state topic. Defaults to `0`. Will also be used when publishing messages. +- **retain** (*Optional*): If the published message should have the retain flag on or not. Defaults to `false`. +- **payload_turn_on** (*Optional*): The payload to send to the `command_topic` to begin the cleaning cycle. Defaults to `turn_on`. +- **payload_turn_off** (*Optional*): The payload to send to the `command_topic` to turn the vacuum off. Defaults to `turn_off`. +- **payload_return_to_base** (*Optional*): The payload to send to the `command_topic` to tell the vacuum to return to base. Defaults to `return_to_base`. +- **payload_stop** (*Optional*): The payload to send to the `command_topic` to stop the vacuum. Defaults to `stop`. +- **payload_clean_spot** (*Optional*): The payload to send to the `command_topic` to begin a spot cleaning cycle. Defaults to `clean_spot`. +- **payload_locate** (*Optional*): The payload to send to the `command_topic` to locate the vacuum (typically plays a song). Defaults to `locate`. +- **payload_start_pause** (*Optional*): The payload to send to the `command_topic` to start or pause the vacuum. Defaults to `start_pause`. +- **battery_level_topic** (*Optional*): The MQTT topic subscribed to receive battery level values from the vacuum. +- **battery_level_template** (*Optional*): Defines a [template](/topics/templating/) to define the battery level of the vacuum. +- **charging_topic** (*Optional*): The MQTT topic subscribed to receive charging state values from the vacuum. +- **charging_template** (*Optional*): Defines a [template](/topics/templating/) to define the charging state of the vacuum. +- **cleaning_topic** (*Optional*): The MQTT topic subscribed to receive cleaning state values from the vacuum. +- **cleaning_template** (*Optional*): Defines a [template](/topics/templating/) to define the cleaning state of the vacuum. +- **docked_topic** (*Optional*): The MQTT topic subscribed to receive docked state values from the vacuum. +- **docked_template** (*Optional*): Defines a [template](/topics/templating/) to define the docked state of the vacuum. +- **fan_speed_topic** (*Optional*): The MQTT topic subscribed to receive fan speed values from the vacuum. +- **fan_speed_template** (*Optional*): Defines a [template](/topics/templating/) to define the fan speed of the vacuum. +- **set_fan_speed_topic** (*Optional*): The MQTT topic to publish commands to control the vacuum's fan speed. +- **fan_speed_list** (*Optional*): List of possible fan speeds for the vacuum. +- **send_command_topic** (*Optional*): The MQTT topic to publish custom commands to the vacuum. + +### {% linkable_title 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: +```json +{ + "battery_level": 61, + "docked": true, + "cleaning": false, + "charging": true, + "fan_speed": "off" +} +``` + +### {% linkable_title Retrofitting a non-wifi Roomba with an ESP8266 %} + +- [This repo](https://github.com/johnboiles/esp-roomba-mqtt) has MQTT client firmware for retrofitting your old Roomba.