mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-15 13:26:54 +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.
|
||||
There are two possible message schemas - `legacy` and `state`, chosen by setting the `schema` configuration parameter.
|
||||
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.
|
||||
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.
|
||||
|
||||
## Configuration
|
||||
|
||||
<a id='new_format'></a>
|
||||
|
||||
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.
|
||||
MQTT vacuum configuration section.
|
||||
|
||||
{% configuration %}
|
||||
availability:
|
||||
@ -488,7 +177,7 @@ retain:
|
||||
type: boolean
|
||||
default: false
|
||||
schema:
|
||||
description: The schema to use. Must be `state` to select the state schema.
|
||||
description: The schema to use. Must be `state`.
|
||||
required: false
|
||||
type: string
|
||||
default: legacy
|
||||
@ -515,7 +204,7 @@ unique_id:
|
||||
type: string
|
||||
{% endconfiguration %}
|
||||
|
||||
### State configuration example
|
||||
## Configuration example
|
||||
|
||||
```yaml
|
||||
# Example configuration.yaml entry
|
||||
@ -545,12 +234,11 @@ mqtt:
|
||||
send_command_topic: "vacuum/send_command"
|
||||
```
|
||||
|
||||
### State MQTT Protocol
|
||||
## MQTT Protocol
|
||||
|
||||
The above configuration for this integration expects an MQTT protocol like the following.
|
||||
See also [Shared MQTT Protocol](#shared-mqtt-protocol).
|
||||
The configuration for this integration expects an MQTT protocol like the following.
|
||||
|
||||
#### State Basic Commands
|
||||
### Basic Commands
|
||||
|
||||
MQTT topic: `vacuum/command`
|
||||
|
||||
@ -563,82 +251,6 @@ Possible MQTT payloads:
|
||||
- `clean_spot` - Initialize a spot cleaning cycle
|
||||
- `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
|
||||
|
||||
Vacuum send_command allows three parameters:
|
||||
@ -676,6 +288,40 @@ Service trigger example:
|
||||
|
||||
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 with cloudless Xiaomi vacuums
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user