From 10ba4504c2a0cd3a08cfc219c362e0875740a77b Mon Sep 17 00:00:00 2001 From: John Boiles Date: Mon, 11 Sep 2017 14:10:15 -0700 Subject: [PATCH 1/6] MQTT Vacuum docs --- source/_components/vacuum.mqtt.markdown | 33 +++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 source/_components/vacuum.mqtt.markdown diff --git a/source/_components/vacuum.mqtt.markdown b/source/_components/vacuum.mqtt.markdown new file mode 100644 index 000000000000..73c1f32ec3cf --- /dev/null +++ b/source/_components/vacuum.mqtt.markdown @@ -0,0 +1,33 @@ +--- +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 +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 minimal configuration.yaml entry +vacuum: + - platform: mqtt +``` + +Configuration variables: + +- **name** (*Optional*): The name of the 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`). Defaults to . +- **state_topic** (*Optional*): The MQTT topic subscribed to receive values from the vacuum. Defaults to `vacuum/state`. +- **command_topic** (*Optional*): The MQTT topic to publish commands to control the vacuum. Defaults to `vacuum/command`. + +### {% 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 From 4881032ba91643bde6ec54d36b75db9775a98be3 Mon Sep 17 00:00:00 2001 From: John Boiles Date: Mon, 11 Sep 2017 14:16:07 -0700 Subject: [PATCH 2/6] Add logo for MQTT Vacuum --- source/_components/vacuum.mqtt.markdown | 1 + 1 file changed, 1 insertion(+) diff --git a/source/_components/vacuum.mqtt.markdown b/source/_components/vacuum.mqtt.markdown index 73c1f32ec3cf..cd55a0614b8d 100644 --- a/source/_components/vacuum.mqtt.markdown +++ b/source/_components/vacuum.mqtt.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +logo: mqtt.png ha_category: Vacuum ha_release: 0.54 --- From 823843a562a57a73b9ddeb6c3bf7ad656cbc6f84 Mon Sep 17 00:00:00 2001 From: John Boiles Date: Wed, 13 Sep 2017 00:25:38 -0700 Subject: [PATCH 3/6] PR fixes --- source/_components/vacuum.mqtt.markdown | 54 +++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 4 deletions(-) diff --git a/source/_components/vacuum.mqtt.markdown b/source/_components/vacuum.mqtt.markdown index cd55a0614b8d..29e288eeb57a 100644 --- a/source/_components/vacuum.mqtt.markdown +++ b/source/_components/vacuum.mqtt.markdown @@ -22,13 +22,59 @@ vacuum: - platform: mqtt ``` -Configuration variables: +```yaml +# Example more advanced configuration.yaml entry +vacuum: + - platform: mqtt + name: "Retro Roomba" + supported_features: + - turn_on + - turn_off + - pause + - stop + - return_home + - battery + - status + - locate + - clean_spot + - fan_speed + - send_command + command_topic: "retroroomba/command" + payload_turn_off: "stop" + payload_locate: "play_song_1" + battery_level_topic: "retroroomba/battery_level" + battery_level_template: "{{ value }}" +``` + +Basic Configuration variables: - **name** (*Optional*): The name of the 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`). Defaults to . -- **state_topic** (*Optional*): The MQTT topic subscribed to receive values from the vacuum. Defaults to `vacuum/state`. +- **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`. + +Advanced Configuration variables: + +- **qos** (*Optional*): The maximum QoS level of the state topic. Default is `0`. Will also be used when publishing messages. +- **retain** (*Optional*): If the published message should have the retain flag on or not. Default is `false`. - **command_topic** (*Optional*): The MQTT topic to publish commands to control the vacuum. Defaults to `vacuum/command`. +- **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. Defaults to `vacuum/state`. +- **battery_level_template** (*Optional*): Defines a [template](/topics/templating/) to define the battery level of the vacuum. Defaults to `{{ value_json.battery_level }}`. +- **charging_topic** (*Optional*): The MQTT topic subscribed to receive charging state values from the vacuum. Defaults to `vacuum/state`. +- **charging_template** (*Optional*): Defines a [template](/topics/templating/) to define the charging state of the vacuum. Defaults to `{{ value_json.charging }}`. +- **state_topic** (*Optional*): The MQTT topic subscribed to receive state value from the vacuum. Defaults to `vacuum/state`. +- **state_template** (*Optional*): Defines a [template](/topics/templating/) to define the state of the vacuum. Defaults to `{{ value_json.state }}`. +- **fan_speed_topic** (*Optional*): The MQTT topic subscribed to receive fan speed values from the vacuum. Defaults to `vacuum/state`. +- **fan_speed_template** (*Optional*): Defines a [template](/topics/templating/) to define the fan speed of the vacuum. Defaults to `{{ value_json.fan_speed }}`. +- **set_fan_speed_topic** (*Optional*): The MQTT topic to publish commands to control the vacuum's fan speed. Defaults to `vacuum/set_fan_speed`. +- **fan_speed_list** (*Optional*): List of possible fan speeds for the vacuum. Defaults to `min`, `medium`, `high`, `max`]. +- **send_command_topic** (*Optional*): The MQTT topic to publish custom commands to the vacuum. Defaults to `vacuum/send_command`. ### {% 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 +- [This repo](https://github.com/johnboiles/esp-roomba-mqtt) has MQTT client firmware for retrofitting your old Roomba. From 85f6d6172ac06806a8dcd48ec15150f3d0c30fa5 Mon Sep 17 00:00:00 2001 From: John Boiles Date: Wed, 13 Sep 2017 01:19:05 -0700 Subject: [PATCH 4/6] Change the state handling to a set of customizable bools --- source/_components/vacuum.mqtt.markdown | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/source/_components/vacuum.mqtt.markdown b/source/_components/vacuum.mqtt.markdown index 29e288eeb57a..6fa66efbd87a 100644 --- a/source/_components/vacuum.mqtt.markdown +++ b/source/_components/vacuum.mqtt.markdown @@ -48,13 +48,13 @@ vacuum: Basic Configuration variables: -- **name** (*Optional*): The name of the vacuum. +- **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`. Advanced Configuration variables: -- **qos** (*Optional*): The maximum QoS level of the state topic. Default is `0`. Will also be used when publishing messages. -- **retain** (*Optional*): If the published message should have the retain flag on or not. Default is `false`. +- **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`. - **command_topic** (*Optional*): The MQTT topic to publish commands to control the vacuum. Defaults to `vacuum/command`. - **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`. @@ -67,8 +67,10 @@ Advanced Configuration variables: - **battery_level_template** (*Optional*): Defines a [template](/topics/templating/) to define the battery level of the vacuum. Defaults to `{{ value_json.battery_level }}`. - **charging_topic** (*Optional*): The MQTT topic subscribed to receive charging state values from the vacuum. Defaults to `vacuum/state`. - **charging_template** (*Optional*): Defines a [template](/topics/templating/) to define the charging state of the vacuum. Defaults to `{{ value_json.charging }}`. -- **state_topic** (*Optional*): The MQTT topic subscribed to receive state value from the vacuum. Defaults to `vacuum/state`. -- **state_template** (*Optional*): Defines a [template](/topics/templating/) to define the state of the vacuum. Defaults to `{{ value_json.state }}`. +- **cleaning_topic** (*Optional*): The MQTT topic subscribed to receive cleaning state values from the vacuum. Defaults to `vacuum/state`. +- **cleaning_template** (*Optional*): Defines a [template](/topics/templating/) to define the cleaning state of the vacuum. Defaults to `{{ value_json.cleaning }}`. +- **docked_topic** (*Optional*): The MQTT topic subscribed to receive docked state values from the vacuum. Defaults to `vacuum/state`. +- **docked_template** (*Optional*): Defines a [template](/topics/templating/) to define the docked state of the vacuum. Defaults to `{{ value_json.docked }}`. - **fan_speed_topic** (*Optional*): The MQTT topic subscribed to receive fan speed values from the vacuum. Defaults to `vacuum/state`. - **fan_speed_template** (*Optional*): Defines a [template](/topics/templating/) to define the fan speed of the vacuum. Defaults to `{{ value_json.fan_speed }}`. - **set_fan_speed_topic** (*Optional*): The MQTT topic to publish commands to control the vacuum's fan speed. Defaults to `vacuum/set_fan_speed`. From 515601ccb68281547104d17219006f920ba8c12b Mon Sep 17 00:00:00 2001 From: John Boiles Date: Wed, 13 Sep 2017 01:19:17 -0700 Subject: [PATCH 5/6] Add info about an example protocol --- source/_components/vacuum.mqtt.markdown | 48 +++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/source/_components/vacuum.mqtt.markdown b/source/_components/vacuum.mqtt.markdown index 6fa66efbd87a..6804eef1a75c 100644 --- a/source/_components/vacuum.mqtt.markdown +++ b/source/_components/vacuum.mqtt.markdown @@ -77,6 +77,54 @@ Advanced Configuration variables: - **fan_speed_list** (*Optional*): List of possible fan speeds for the vacuum. Defaults to `min`, `medium`, `high`, `max`]. - **send_command_topic** (*Optional*): The MQTT topic to publish custom commands to the vacuum. Defaults to `vacuum/send_command`. +### {% linkable_title Default MQTT Protocol %} + +The default 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. From 3208086aa03e3b1f50cb2a7723ae7d7e80d5f16d Mon Sep 17 00:00:00 2001 From: John Boiles Date: Fri, 15 Sep 2017 22:20:17 -0700 Subject: [PATCH 6/6] RIP Defaults --- source/_components/vacuum.mqtt.markdown | 63 ++++++++++++++----------- 1 file changed, 35 insertions(+), 28 deletions(-) diff --git a/source/_components/vacuum.mqtt.markdown b/source/_components/vacuum.mqtt.markdown index 6804eef1a75c..c8b45ff6119e 100644 --- a/source/_components/vacuum.mqtt.markdown +++ b/source/_components/vacuum.mqtt.markdown @@ -17,16 +17,10 @@ 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 minimal configuration.yaml entry +# Example configuration.yaml entry vacuum: - platform: mqtt -``` - -```yaml -# Example more advanced configuration.yaml entry -vacuum: - - platform: mqtt - name: "Retro Roomba" + name: "MQTT Vacuum" supported_features: - turn_on - turn_off @@ -39,23 +33,36 @@ vacuum: - clean_spot - fan_speed - send_command - command_topic: "retroroomba/command" - payload_turn_off: "stop" - payload_locate: "play_song_1" - battery_level_topic: "retroroomba/battery_level" - battery_level_template: "{{ value }}" + 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`. -- **command_topic** (*Optional*): The MQTT topic to publish commands to control the vacuum. Defaults to `vacuum/command`. - **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`. @@ -63,23 +70,23 @@ Advanced Configuration variables: - **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. Defaults to `vacuum/state`. -- **battery_level_template** (*Optional*): Defines a [template](/topics/templating/) to define the battery level of the vacuum. Defaults to `{{ value_json.battery_level }}`. -- **charging_topic** (*Optional*): The MQTT topic subscribed to receive charging state values from the vacuum. Defaults to `vacuum/state`. -- **charging_template** (*Optional*): Defines a [template](/topics/templating/) to define the charging state of the vacuum. Defaults to `{{ value_json.charging }}`. -- **cleaning_topic** (*Optional*): The MQTT topic subscribed to receive cleaning state values from the vacuum. Defaults to `vacuum/state`. -- **cleaning_template** (*Optional*): Defines a [template](/topics/templating/) to define the cleaning state of the vacuum. Defaults to `{{ value_json.cleaning }}`. -- **docked_topic** (*Optional*): The MQTT topic subscribed to receive docked state values from the vacuum. Defaults to `vacuum/state`. -- **docked_template** (*Optional*): Defines a [template](/topics/templating/) to define the docked state of the vacuum. Defaults to `{{ value_json.docked }}`. -- **fan_speed_topic** (*Optional*): The MQTT topic subscribed to receive fan speed values from the vacuum. Defaults to `vacuum/state`. -- **fan_speed_template** (*Optional*): Defines a [template](/topics/templating/) to define the fan speed of the vacuum. Defaults to `{{ value_json.fan_speed }}`. -- **set_fan_speed_topic** (*Optional*): The MQTT topic to publish commands to control the vacuum's fan speed. Defaults to `vacuum/set_fan_speed`. -- **fan_speed_list** (*Optional*): List of possible fan speeds for the vacuum. Defaults to `min`, `medium`, `high`, `max`]. -- **send_command_topic** (*Optional*): The MQTT topic to publish custom commands to the vacuum. Defaults to `vacuum/send_command`. +- **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 default configuration for this component expects an MQTT protocol like the following. +The above configuration for this component expects an MQTT protocol like the following. #### Basic Commands