mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-15 21:36:52 +00:00
Remove documentation of deprecated MQTT vacuum protocol (#28056)
This commit is contained in:
Erik Montnemery
GitHub
parent
f52b65b07d
commit
db3be58eeb
@ -8,322 +8,11 @@ ha_domain: mqtt
|
|||||||
---
|
---
|
||||||
|
|
||||||
The `mqtt` vacuum integration allows you to control your MQTT-enabled vacuum.
|
The `mqtt` vacuum integration allows you to control your MQTT-enabled vacuum.
|
||||||
There are two possible message schemas - `legacy` and `state`, chosen by setting the `schema` configuration parameter.
|
The initial state of the MQTT vacuum entity will set to `unknown` and can be reset by a device by sending a `null` payload as state.
|
||||||
New installations should use the `state` schema as `legacy` is deprecated and might be removed someday in the future.
|
|
||||||
The `state` schema is preferred because the vacuum will then be represented as a `StateVacuumDevice` which is the preferred parent vacuum entity.
|
|
||||||
The initial state of the state vacuum entity will set to `unknown` and can be reset by a device by sending a `null` payload as state. The legacy `mqtt` vacuum does not support handling an `unknown` state.
|
|
||||||
|
|
||||||
This documentation has 3 sections. Configuration for `legacy` vacuum with examples, configuration for `state` vacuum with examples and shared section with examples which are the same for both schemas.
|
|
||||||
|
|
||||||
## Configuration
|
## Configuration
|
||||||
|
|
||||||
<a id='new_format'></a>
|
MQTT vacuum configuration section.
|
||||||
|
|
||||||
To add your MQTT vacuum to your installation, add the following to your `configuration.yaml` file:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# Example configuration.yaml entry
|
|
||||||
mqtt:
|
|
||||||
vacuum:
|
|
||||||
- command_topic: "vacuum/command"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Legacy Configuration
|
|
||||||
|
|
||||||
Legacy MQTT vacuum configuration section.
|
|
||||||
|
|
||||||
{% configuration %}
|
|
||||||
availability:
|
|
||||||
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
|
|
||||||
required: false
|
|
||||||
type: list
|
|
||||||
keys:
|
|
||||||
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
|
|
||||||
topic:
|
|
||||||
description: An MQTT topic subscribed to receive availability (online/offline) updates.
|
|
||||||
required: true
|
|
||||||
type: string
|
|
||||||
value_template:
|
|
||||||
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract device's availability from the `topic`. To determine the devices's availability result of this template will be compared to `payload_available` and `payload_not_available`."
|
|
||||||
required: false
|
|
||||||
type: template
|
|
||||||
availability_mode:
|
|
||||||
description: When `availability` is configured, this controls the conditions needed to set the entity to `available`. Valid entries are `all`, `any`, and `latest`. If set to `all`, `payload_available` must be received on all configured availability topics before the entity is marked as online. If set to `any`, `payload_available` must be received on at least one configured availability topic before the entity is marked as online. If set to `latest`, the last `payload_available` or `payload_not_available` received on any configured availability topic controls the availability.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
default: latest
|
|
||||||
availability_template:
|
|
||||||
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract device's availability from the `availability_topic`. To determine the devices's availability result of this template will be compared to `payload_available` and `payload_not_available`."
|
|
||||||
required: false
|
|
||||||
type: template
|
|
||||||
availability_topic:
|
|
||||||
description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
battery_level_template:
|
|
||||||
description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to define the battery level of the vacuum. This is required if `battery_level_topic` is set.
|
|
||||||
required: false
|
|
||||||
type: template
|
|
||||||
battery_level_topic:
|
|
||||||
description: The MQTT topic subscribed to receive battery level values from the vacuum.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
charging_template:
|
|
||||||
description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to define the charging state of the vacuum. This is required if `charging_topic` is set.
|
|
||||||
required: false
|
|
||||||
type: template
|
|
||||||
charging_topic:
|
|
||||||
description: The MQTT topic subscribed to receive charging state values from the vacuum.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
cleaning_template:
|
|
||||||
description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to define the cleaning state of the vacuum. This is required if `cleaning_topic` is set.
|
|
||||||
required: false
|
|
||||||
type: template
|
|
||||||
cleaning_topic:
|
|
||||||
description: The MQTT topic subscribed to receive cleaning state values from the vacuum.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
command_topic:
|
|
||||||
description: The MQTT topic to publish commands to control the vacuum.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
docked_template:
|
|
||||||
description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to define the docked state of the vacuum. This is required if `docked_topic` is set.
|
|
||||||
required: false
|
|
||||||
type: template
|
|
||||||
docked_topic:
|
|
||||||
description: The MQTT topic subscribed to receive docked state values from the vacuum.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
enabled_by_default:
|
|
||||||
description: Flag which defines if the entity should be enabled when first added.
|
|
||||||
required: false
|
|
||||||
type: boolean
|
|
||||||
default: true
|
|
||||||
encoding:
|
|
||||||
description: The encoding of the payloads received and published messages. Set to `""` to disable decoding of incoming payload.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
default: "utf-8"
|
|
||||||
entity_category:
|
|
||||||
description: The [category](https://developers.home-assistant.io/docs/core/entity#generic-properties) of the entity.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
default: None
|
|
||||||
error_template:
|
|
||||||
description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to define potential error messages emitted by the vacuum. This is required if `error_topic` is set.
|
|
||||||
required: false
|
|
||||||
type: template
|
|
||||||
error_topic:
|
|
||||||
description: The MQTT topic subscribed to receive error messages from the vacuum.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
fan_speed_list:
|
|
||||||
description: List of possible fan speeds for the vacuum.
|
|
||||||
required: false
|
|
||||||
type: [string, list]
|
|
||||||
fan_speed_template:
|
|
||||||
description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to define the fan speed of the vacuum. This is required if `fan_speed_topic` is set.
|
|
||||||
required: false
|
|
||||||
type: template
|
|
||||||
fan_speed_topic:
|
|
||||||
description: The MQTT topic subscribed to receive fan speed values from the vacuum.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
icon:
|
|
||||||
description: "[Icon](/docs/configuration/customizing-devices/#icon) for the entity."
|
|
||||||
required: false
|
|
||||||
type: icon
|
|
||||||
json_attributes_template:
|
|
||||||
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the JSON dictionary from messages received on the `json_attributes_topic`. Usage example can be found in [MQTT sensor](/integrations/sensor.mqtt/#json-attributes-template-configuration) documentation."
|
|
||||||
required: false
|
|
||||||
type: template
|
|
||||||
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](/integrations/sensor.mqtt/#json-attributes-topic-configuration) documentation.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
name:
|
|
||||||
description: The name of the vacuum.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
default: MQTT Vacuum
|
|
||||||
object_id:
|
|
||||||
description: Used instead of `name` for automatic generation of `entity_id`
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
payload_available:
|
|
||||||
description: The payload that represents the available state.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
default: online
|
|
||||||
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_not_available:
|
|
||||||
description: The payload that represents the unavailable state.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
default: offline
|
|
||||||
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_start_pause:
|
|
||||||
description: The payload to send to the `command_topic` to start or pause the vacuum.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
default: start_pause
|
|
||||||
payload_stop:
|
|
||||||
description: The payload to send to the `command_topic` to stop the vacuum.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
default: stop
|
|
||||||
payload_turn_off:
|
|
||||||
description: The payload to send to the `command_topic` to turn the vacuum off.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
default: turn_off
|
|
||||||
payload_turn_on:
|
|
||||||
description: The payload to send to the `command_topic` to begin the cleaning cycle.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
default: turn_on
|
|
||||||
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
|
|
||||||
schema:
|
|
||||||
description: The schema to use. Must be `legacy` or omitted to select the legacy schema.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
default: legacy
|
|
||||||
send_command_topic:
|
|
||||||
description: The MQTT topic to publish custom commands to 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
|
|
||||||
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`).
|
|
||||||
required: false
|
|
||||||
type: [string, list]
|
|
||||||
default: "`turn_on`, `turn_off`, `stop`, `return_home`, `status`, `battery`, `clean_spot`"
|
|
||||||
unique_id:
|
|
||||||
description: An ID that uniquely identifies this vacuum. If two vacuums have the same unique ID, Home Assistant will raise an exception.
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
{% endconfiguration %}
|
|
||||||
|
|
||||||
### Legacy configuration example
|
|
||||||
|
|
||||||
{% raw %}
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# Example configuration.yaml entry
|
|
||||||
mqtt:
|
|
||||||
vacuum:
|
|
||||||
- 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 }}"
|
|
||||||
error_topic: "vacuum/state"
|
|
||||||
error_template: "{{ value_json.error }}"
|
|
||||||
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"
|
|
||||||
```
|
|
||||||
|
|
||||||
{% endraw %}
|
|
||||||
|
|
||||||
### Legacy MQTT Protocol
|
|
||||||
|
|
||||||
The above configuration for this integration expects an MQTT protocol like the following.
|
|
||||||
See also [Shared MQTT Protocol](#shared-mqtt-protocol).
|
|
||||||
|
|
||||||
#### Legacy 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
|
|
||||||
|
|
||||||
#### Status/Sensor Updates
|
|
||||||
|
|
||||||
MQTT topic: `vacuum/state`
|
|
||||||
|
|
||||||
MQTT payload:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"battery_level": 61,
|
|
||||||
"docked": true,
|
|
||||||
"cleaning": false,
|
|
||||||
"charging": true,
|
|
||||||
"fan_speed": "off",
|
|
||||||
"error": "Error message"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## State Configuration
|
|
||||||
|
|
||||||
State MQTT vacuum configuration section.
|
|
||||||
|
|
||||||
{% configuration %}
|
{% configuration %}
|
||||||
availability:
|
availability:
|
||||||
@ -488,7 +177,7 @@ retain:
|
|||||||
type: boolean
|
type: boolean
|
||||||
default: false
|
default: false
|
||||||
schema:
|
schema:
|
||||||
description: The schema to use. Must be `state` to select the state schema.
|
description: The schema to use. Must be `state`.
|
||||||
required: false
|
required: false
|
||||||
type: string
|
type: string
|
||||||
default: legacy
|
default: legacy
|
||||||
@ -515,7 +204,7 @@ unique_id:
|
|||||||
type: string
|
type: string
|
||||||
{% endconfiguration %}
|
{% endconfiguration %}
|
||||||
|
|
||||||
### State configuration example
|
## Configuration example
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
# Example configuration.yaml entry
|
# Example configuration.yaml entry
|
||||||
@ -545,12 +234,11 @@ mqtt:
|
|||||||
send_command_topic: "vacuum/send_command"
|
send_command_topic: "vacuum/send_command"
|
||||||
```
|
```
|
||||||
|
|
||||||
### State MQTT Protocol
|
## MQTT Protocol
|
||||||
|
|
||||||
The above configuration for this integration expects an MQTT protocol like the following.
|
The configuration for this integration expects an MQTT protocol like the following.
|
||||||
See also [Shared MQTT Protocol](#shared-mqtt-protocol).
|
|
||||||
|
|
||||||
#### State Basic Commands
|
### Basic Commands
|
||||||
|
|
||||||
MQTT topic: `vacuum/command`
|
MQTT topic: `vacuum/command`
|
||||||
|
|
||||||
@ -563,82 +251,6 @@ Possible MQTT payloads:
|
|||||||
- `clean_spot` - Initialize a spot cleaning cycle
|
- `clean_spot` - Initialize a spot cleaning cycle
|
||||||
- `locate` - Locate the vacuum (typically by playing a song)
|
- `locate` - Locate the vacuum (typically by playing a song)
|
||||||
|
|
||||||
#### 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:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
'command': 'command',
|
|
||||||
'param1-key': 'param1-value'
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Service trigger example:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
- alias: "Push command based on sensor"
|
|
||||||
trigger:
|
|
||||||
- platform: state
|
|
||||||
entity_id: sensor.sensor
|
|
||||||
action:
|
|
||||||
service: vacuum.send_command
|
|
||||||
target:
|
|
||||||
entity_id: vacuum.vacuum_entity
|
|
||||||
data:
|
|
||||||
command: "custom_command"
|
|
||||||
params:
|
|
||||||
- key: value
|
|
||||||
```
|
|
||||||
|
|
||||||
MQTT topic: `vacuum/send_command`
|
|
||||||
|
|
||||||
#### 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.
|
|
||||||
|
|
||||||
## Shared MQTT Protocol
|
|
||||||
|
|
||||||
The configuration for this integration expects an MQTT protocol like the following.
|
|
||||||
These services are identical for both - legacy and state vacuum.
|
|
||||||
|
|
||||||
### 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
|
### Send Custom Command
|
||||||
|
|
||||||
Vacuum send_command allows three parameters:
|
Vacuum send_command allows three parameters:
|
||||||
@ -676,6 +288,40 @@ Service trigger example:
|
|||||||
|
|
||||||
MQTT topic: `vacuum/send_command`
|
MQTT topic: `vacuum/send_command`
|
||||||
|
|
||||||
|
### 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.
|
||||||
|
|
||||||
|
### 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
|
||||||
|
|
||||||
## Usage examples
|
## Usage examples
|
||||||
|
|
||||||
### Usage with cloudless Xiaomi vacuums
|
### Usage with cloudless Xiaomi vacuums
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user