Skip to content

Commit 28b5ca9

Browse files
johnboilesballoob
johnboiles
authored and
balloob
committed
MQTT Vacuum docs (home-assistant#3354)
* MQTT Vacuum docs * Add logo for MQTT Vacuum * PR fixes * Change the state handling to a set of customizable bools * Add info about an example protocol * RIP Defaults
1 parent 1c43059 commit 28b5ca9

File tree

1 file changed

+137
-0
lines changed

1 file changed

+137
-0
lines changed

‎source/_components/vacuum.mqtt.markdown

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
layout: page
3+
title: "MQTT"
4+
description: "Instructions how to integrate your MQTT enabled Vacuum within Home Assistant."
5+
date: 2017-09-11 20:26
6+
sidebar: true
7+
comments: false
8+
sharing: true
9+
footer: true
10+
logo: mqtt.png
11+
ha_category: Vacuum
12+
ha_release: 0.54
13+
---
14+
15+
The `mqtt` component allows you to control your MQTT-enabled vacuum.
16+
17+
To add your MQTT vacuum to your installation, add the following to your `configuration.yaml` file:
18+
19+
```yaml
20+
# Example configuration.yaml entry
21+
vacuum:
22+
- platform: mqtt
23+
name: "MQTT Vacuum"
24+
supported_features:
25+
- turn_on
26+
- turn_off
27+
- pause
28+
- stop
29+
- return_home
30+
- battery
31+
- status
32+
- locate
33+
- clean_spot
34+
- fan_speed
35+
- send_command
36+
command_topic: "vacuum/command"
37+
battery_level_topic: "vacuum/state"
38+
battery_level_template: "{{ value_json.battery_level }}"
39+
charging_topic: "vacuum/state"
40+
charging_template: "{{ value_json.charging }}"
41+
cleaning_topic: "vacuum/state"
42+
cleaning_template: "{{ value_json.cleaning }}"
43+
docked_topic: "vacuum/state"
44+
docked_template: "{{ value_json.docked }}"
45+
fan_speed_topic: "vacuum/state"
46+
fan_speed_template: "{{ value_json.fan_speed }}"
47+
set_fan_speed_topic: "vacuum/set_fan_speed"
48+
fan_speed_list:
49+
- min
50+
- medium
51+
- high
52+
- max
53+
send_command_topic: 'vacuum/send_command'
54+
```
55+
56+
Basic Configuration variables:
57+
58+
- **name** (*Optional*): The name of the vacuum. Defaults to `MQTT Vacuum`.
59+
- **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`.
60+
- **command_topic** (*Optional*): The MQTT topic to publish commands to control the vacuum.
61+
62+
Advanced Configuration variables:
63+
64+
- **qos** (*Optional*): The maximum QoS level of the state topic. Defaults to `0`. Will also be used when publishing messages.
65+
- **retain** (*Optional*): If the published message should have the retain flag on or not. Defaults to `false`.
66+
- **payload_turn_on** (*Optional*): The payload to send to the `command_topic` to begin the cleaning cycle. Defaults to `turn_on`.
67+
- **payload_turn_off** (*Optional*): The payload to send to the `command_topic` to turn the vacuum off. Defaults to `turn_off`.
68+
- **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`.
69+
- **payload_stop** (*Optional*): The payload to send to the `command_topic` to stop the vacuum. Defaults to `stop`.
70+
- **payload_clean_spot** (*Optional*): The payload to send to the `command_topic` to begin a spot cleaning cycle. Defaults to `clean_spot`.
71+
- **payload_locate** (*Optional*): The payload to send to the `command_topic` to locate the vacuum (typically plays a song). Defaults to `locate`.
72+
- **payload_start_pause** (*Optional*): The payload to send to the `command_topic` to start or pause the vacuum. Defaults to `start_pause`.
73+
- **battery_level_topic** (*Optional*): The MQTT topic subscribed to receive battery level values from the vacuum.
74+
- **battery_level_template** (*Optional*): Defines a [template](/topics/templating/) to define the battery level of the vacuum.
75+
- **charging_topic** (*Optional*): The MQTT topic subscribed to receive charging state values from the vacuum.
76+
- **charging_template** (*Optional*): Defines a [template](/topics/templating/) to define the charging state of the vacuum.
77+
- **cleaning_topic** (*Optional*): The MQTT topic subscribed to receive cleaning state values from the vacuum.
78+
- **cleaning_template** (*Optional*): Defines a [template](/topics/templating/) to define the cleaning state of the vacuum.
79+
- **docked_topic** (*Optional*): The MQTT topic subscribed to receive docked state values from the vacuum.
80+
- **docked_template** (*Optional*): Defines a [template](/topics/templating/) to define the docked state of the vacuum.
81+
- **fan_speed_topic** (*Optional*): The MQTT topic subscribed to receive fan speed values from the vacuum.
82+
- **fan_speed_template** (*Optional*): Defines a [template](/topics/templating/) to define the fan speed of the vacuum.
83+
- **set_fan_speed_topic** (*Optional*): The MQTT topic to publish commands to control the vacuum's fan speed.
84+
- **fan_speed_list** (*Optional*): List of possible fan speeds for the vacuum.
85+
- **send_command_topic** (*Optional*): The MQTT topic to publish custom commands to the vacuum.
86+
87+
### {% linkable_title Default MQTT Protocol %}
88+
89+
The above configuration for this component expects an MQTT protocol like the following.
90+
91+
#### Basic Commands
92+
93+
MQTT topic: `vacuum/command`
94+
95+
Possible MQTT payloads:
96+
- `turn_on` - Begin cleaning
97+
- `turn_off` - Turn the Vacuum off
98+
- `return_to_base` - Return to base/dock
99+
- `stop` - Stop the Vacuum
100+
- `clean_spot` - Initialize a spot cleaning cycle
101+
- `locate` - Locate the vacuum (typically by playing a song)
102+
- `start_pause` - Toggle the vacuum between cleaning and stopping
103+
104+
#### Set Fan Speed
105+
106+
MQTT topic: `vacuum/set_fan_speed`
107+
108+
Possible MQTT payloads:
109+
- `min` - Minimum fan speed
110+
- `medium` - Medium fan speed
111+
- `high` - High fan speed
112+
- `max` - Max fan speed
113+
114+
#### Send Custom Command
115+
116+
MQTT topic: `vacuum/send_command`
117+
118+
MQTT payload for `send_command` can be an arbitrary value handled by the vacuum's MQTT-enabled firmware.
119+
120+
#### Status/Sensor Updates
121+
122+
MQTT topic: `vacuum/state`
123+
124+
MQTT payload:
125+
```json
126+
{
127+
"battery_level": 61,
128+
"docked": true,
129+
"cleaning": false,
130+
"charging": true,
131+
"fan_speed": "off"
132+
}
133+
```
134+
135+
### {% linkable_title Retrofitting a non-wifi Roomba with an ESP8266 %}
136+
137+
- [This repo](https://github.com/johnboiles/esp-roomba-mqtt) has MQTT client firmware for retrofitting your old Roomba.

0 commit comments

Comments
 (0)