mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-23 09:17:06 +00:00
new schema Mqtt State Vacuum (#9281)
* mqtt vacuum new schema. * add state to mqtt config. * info about StateVacuumDevice * tag fixes * ✏️ Tweak * ✏️ Tweak * ✏️ Tweak (last round)
This commit is contained in:
Pawel
Klaas Schoute
parent
d46ee49b33
commit
7eb9fd5688
@ -13,6 +13,11 @@ ha_release: 0.54
|
||||
---
|
||||
|
||||
The `mqtt` vacuum component allows you to control your MQTT-enabled vacuum.
|
||||
There are 2 possible message schemas - `legacy` and `state`.
|
||||
New installation should use `state` schema as `legacy` is deprecated and might be removed someday in the future.
|
||||
`state` schema is preferred because the vacuum will then be represented as a `StateVacuumDevice` which is preferred parent vacuum entity.
|
||||
|
||||
This documentation has 3 sections. Config for `legacy` vacuum with examples, config for `state` vacuum with examples and shared section with examples which are the same for both schemas.
|
||||
|
||||
## {% linkable_title Configuration %}
|
||||
|
||||
@ -24,14 +29,23 @@ vacuum:
|
||||
- platform: mqtt
|
||||
```
|
||||
|
||||
## {% linkable_title Legacy Configuration %}
|
||||
|
||||
Legacy MQTT vacuum configuration section.
|
||||
|
||||
{% configuration %}
|
||||
name:
|
||||
description: The name of the vacuum.
|
||||
required: false
|
||||
type: string
|
||||
default: MQTT Vacuum
|
||||
schema:
|
||||
description: The schema to use.
|
||||
required: false
|
||||
type: string
|
||||
default: legacy
|
||||
supported_features:
|
||||
description: "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`)."
|
||||
description: 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`)."
|
||||
required: false
|
||||
type: string list
|
||||
default: "`turn_on`, `turn_off`, `stop`, `return_home`, `status`, `battery`, `clean_spot`"
|
||||
@ -168,7 +182,7 @@ json_attributes_template:
|
||||
type: template
|
||||
{% endconfiguration %}
|
||||
|
||||
### {% linkable_title Full configuration example %}
|
||||
### {% linkable_title Legacy configuration example %}
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
@ -211,11 +225,11 @@ vacuum:
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### {% linkable_title Default MQTT Protocol %}
|
||||
## {% linkable_title Legacy MQTT Protocol %}
|
||||
|
||||
The above configuration for this component expects an MQTT protocol like the following.
|
||||
|
||||
#### {% linkable_title Basic Commands %}
|
||||
### {% linkable_title Legacy Basic Commands %}
|
||||
|
||||
MQTT topic: `vacuum/command`
|
||||
|
||||
@ -229,52 +243,7 @@ Possible MQTT payloads:
|
||||
- `locate` - Locate the vacuum (typically by playing a song)
|
||||
- `start_pause` - Toggle the vacuum between cleaning and stopping
|
||||
|
||||
#### {% linkable_title 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
|
||||
|
||||
#### {% linkable_title 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:
|
||||
```
|
||||
{
|
||||
'command': 'command',
|
||||
'param1-key': 'param1-value'
|
||||
}
|
||||
```
|
||||
|
||||
Service trigger example:
|
||||
```
|
||||
- alias: Push command based on sensor
|
||||
trigger:
|
||||
- platform: state
|
||||
entity_id: sensor.sensor
|
||||
action:
|
||||
service: vacuum.send_command
|
||||
data:
|
||||
entity_id: 'vacuum.vacuum_entity'
|
||||
command: 'custom_command'
|
||||
params:
|
||||
- key: value
|
||||
```
|
||||
|
||||
MQTT topic: `vacuum/send_command`
|
||||
|
||||
#### {% linkable_title Status/Sensor Updates %}
|
||||
### {% linkable_title Status/Sensor Updates %}
|
||||
|
||||
MQTT topic: `vacuum/state`
|
||||
|
||||
@ -291,6 +260,270 @@ MQTT payload:
|
||||
}
|
||||
```
|
||||
|
||||
## {% linkable_title State Configuration %}
|
||||
|
||||
State MQTT vacuum configuration section.
|
||||
|
||||
{% configuration %}
|
||||
name:
|
||||
description: The name of the vacuum.
|
||||
required: false
|
||||
type: string
|
||||
default: MQTT Vacuum
|
||||
schema:
|
||||
description: The schema to use.
|
||||
required: false
|
||||
type: string
|
||||
default: legacy
|
||||
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`"
|
||||
command_topic:
|
||||
description: The MQTT topic to publish commands to control the vacuum.
|
||||
required: false
|
||||
type: string
|
||||
qos:
|
||||
description: The maximum QoS level of the state topic.
|
||||
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
|
||||
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
|
||||
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_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_pause:
|
||||
description: The payload to send to the `command_topic` to pause the vacuum.
|
||||
required: false
|
||||
type: string
|
||||
default: pause
|
||||
state_topic:
|
||||
description: The MQTT topic subscribed to receive state messages from the vacuum. State topic is extracting json if no `value_template` is defined.
|
||||
required: false
|
||||
type: string
|
||||
value_template:
|
||||
description: "Defines a [template](/topics/templating/) to extract possible states from 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
|
||||
fan_speed_list:
|
||||
description: List of possible fan speeds for the vacuum.
|
||||
required: false
|
||||
type: string list
|
||||
send_command_topic:
|
||||
description: The MQTT topic to publish custom commands to the vacuum.
|
||||
required: false
|
||||
type: string
|
||||
availability_topic:
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
required: false
|
||||
type: string
|
||||
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
|
||||
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](/components/sensor.mqtt/#json-attributes-topic-configuration) documentation.
|
||||
required: false
|
||||
type: string
|
||||
{% endconfiguration %}
|
||||
|
||||
### {% linkable_title State configuration example %}
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
# Example configuration.yaml entry
|
||||
vacuum:
|
||||
- platform: mqtt
|
||||
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'
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
## {% linkable_title State MQTT Protocol %}
|
||||
|
||||
The above configuration for this component expects an MQTT protocol like the following.
|
||||
|
||||
### {% linkable_title State 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)
|
||||
|
||||
### {% linkable_title 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:
|
||||
|
||||
```
|
||||
{
|
||||
'command': 'command',
|
||||
'param1-key': 'param1-value'
|
||||
}
|
||||
```
|
||||
|
||||
Service trigger example:
|
||||
|
||||
```
|
||||
- alias: Push command based on sensor
|
||||
trigger:
|
||||
- platform: state
|
||||
entity_id: sensor.sensor
|
||||
action:
|
||||
service: vacuum.send_command
|
||||
data:
|
||||
entity_id: 'vacuum.vacuum_entity'
|
||||
command: 'custom_command'
|
||||
params:
|
||||
- key: value
|
||||
```
|
||||
|
||||
MQTT topic: `vacuum/send_command`
|
||||
|
||||
### {% linkable_title 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.
|
||||
|
||||
## {% linkable_title Shared MQTT Protocol %}
|
||||
|
||||
The configuration for this component expects an MQTT protocol like the following.
|
||||
These services are identical for both - legacy and state vacuum.
|
||||
|
||||
### {% linkable_title 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
|
||||
|
||||
### {% linkable_title 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:
|
||||
|
||||
```
|
||||
{
|
||||
'command': 'command',
|
||||
'param1-key': 'param1-value'
|
||||
}
|
||||
```
|
||||
|
||||
Service trigger example:
|
||||
|
||||
```
|
||||
- alias: Push command based on sensor
|
||||
trigger:
|
||||
- platform: state
|
||||
entity_id: sensor.sensor
|
||||
action:
|
||||
service: vacuum.send_command
|
||||
data:
|
||||
entity_id: 'vacuum.vacuum_entity'
|
||||
command: 'custom_command'
|
||||
params:
|
||||
- key: value
|
||||
```
|
||||
|
||||
MQTT topic: `vacuum/send_command`
|
||||
|
||||
### {% linkable_title Usage with cloudless Xiaomi vacuums %}
|
||||
|
||||
This component is supported by the cloud-free Xiaomi Vacuum Webinterface [Valetudo](https://github.com/Hypfer/Valetudo).
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user