From db3be58eeb80a433049bbf80a659befd3c7ecfa1 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Tue, 4 Jul 2023 08:40:46 +0200 Subject: [PATCH] Remove documentation of deprecated MQTT vacuum protocol (#28056) --- source/_integrations/vacuum.mqtt.markdown | 436 ++-------------------- 1 file changed, 41 insertions(+), 395 deletions(-) diff --git a/source/_integrations/vacuum.mqtt.markdown b/source/_integrations/vacuum.mqtt.markdown index d6d75b6248b..480c1dedef3 100644 --- a/source/_integrations/vacuum.mqtt.markdown +++ b/source/_integrations/vacuum.mqtt.markdown @@ -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 - - -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