Make sure that your topics match exactly. `some-topic/` and `some-topic` are different topics. diff --git a/source/_components/light.mqtt.markdown b/source/_components/light.mqtt.markdown index ba3041dde38..33f76eb5cc1 100644 --- a/source/_components/light.mqtt.markdown +++ b/source/_components/light.mqtt.markdown @@ -27,39 +27,153 @@ light: command_topic: "office/rgb1/light/switch" ``` -Configuration variables: - -- **command_topic** (*Required*): The MQTT topic to publish commands to change the switch state. -- **brightness_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's brightness. -- **brightness_scale** (*Optional*): Defines the maximum brightness value (i.e. 100%) of the MQTT device (defaults to 255). -- **brightness_state_topic** (*Optional*): The MQTT topic subscribed to receive brightness state updates. -- **brightness_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the brightness value. -- **color_temp_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's color temperature state. The color temperature command slider has a range of 157 to 500 mireds (micro reciprocal degrees). -- **color_temp_state_topic** (*Optional*): The MQTT topic subscribed to receive color temperature state updates. -- **color_temp_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the color temperature value. -- **effect_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's effect state. -- **effect_state_topic** (*Optional*): The MQTT topic subscribed to receive effect state updates. -- **effect_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the effect value. -- **effect_list** (*Optional*): The list of effects the light supports. -- **name** (*Optional*): The name of the switch. Default is 'MQTT Switch'. -- **on_command_type** (*Optional*): Defines when on the payload_on is sent. Using `last` (the default) will send any style (brightness, color, etc) topics first and then a `payload_on` to the `command_topic`. Using `first` will send the `payload_on` and then any style topics. Using `brightness` will only send brightness commands instead of the `payload_on` to turn the light on. -- **optimistic** (*Optional*): Flag that defines if switch works in optimistic mode. Default is true if no state topic defined, else false. -- **payload_off** (*Optional*): The payload that represents disabled state. Default is "OFF". -- **payload_on** (*Optional*): The payload that represents enabled state. Default is "ON". -- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages. -- **retain** (*Optional*): If the published message should have the retain flag on or not. -- **rgb_command_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to compose message which will be sent to `rgb_command_topic`. Available variables: `red`, `green` and `blue`. -- **rgb_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's RGB state. -- **rgb_state_topic** (*Optional*): The MQTT topic subscribed to receive RGB state updates. -- **rgb_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the RGB value. -- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates. -- **state_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the state value. The template should match the payload "on" and "off" values, so if your light uses "power on" to turn on, your `state_value_template` string should return "power on" when the switch is on. For example if the message is just "on", your `state_value_template` should be `power {{ value }}`. -- **white_value_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's white value. -- **white_value_state_topic** (*Optional*): The MQTT topic subscribed to receive white value updates. -- **white_value_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the white value. -- **xy_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's XY state. -- **xy_state_topic** (*Optional*): The MQTT topic subscribed to receive XY state updates. -- **xy_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the XY value. +{% configuration %} +name: + description: The name of the light. + required: false + type: string + default: MQTT Light +command_topic: + description: The MQTT topic to publish commands to change the switch state. + required: true + type: string +brightness_command_topic: + description: The MQTT topic to publish commands to change the light’s brightness. + required: false + type: string +brightness_scale: + description: "Defines the maximum brightness value (i.e. 100%) of the MQTT device." + required: false + type: integer + default: 255 +brightness_state_topic: + description: The MQTT topic subscribed to receive brightness state updates. + required: false + type: string +brightness_value_template: + description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the brightness value." + required: false + type: string +color_temp_command_topic: + description: The MQTT topic to publish commands to change the light’s color temperature state. The color temperature command slider has a range of 157 to 500 mireds (micro reciprocal degrees). + required: false + type: string +color_temp_state_topic: + description: The MQTT topic subscribed to receive color temperature state updates. + required: false + type: string +color_temp_value_template: + description: "Defines a [template](/topics/templating/) to extract the color temperature value." + required: false + type: string +effect_command_topic: + description: "The MQTT topic to publish commands to change the light's effect state." + required: false + type: string +effect_state_topic: + description: The MQTT topic subscribed to receive effect state updates. + required: false + type: string +effect_value_template: + description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the effect value." + required: false + type: string +effect_list: + description: The list of effects the light supports. + required: false + type: string list +on_command_type: + description: "Defines when on the payload_on is sent. Using `last` (the default) will send any style (brightness, color, etc) topics first and then a `payload_on` to the `command_topic`. Using `first` will send the `payload_on` and then any style topics. Using `brightness` will only send brightness commands instead of the `payload_on` to turn the light on." + required: false + type: string +optimistic: + description: Flag that defines if switch works in optimistic mode. + required: false + type: boolean + default: "`true` if no state topic defined, else `false`." +payload_on: + description: The payload that represents enabled state. + required: false + type: string + default: ON +payload_off: + description: The payload that represents disabled state. + required: false + type: string + default: OFF +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 +rgb_command_template: + description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to compose message which will be sent to `rgb_command_topic`. Available variables: `red`, `green` and `blue`." + required: false + type: string +rgb_command_topic: + description: "The MQTT topic to publish commands to change the light's RGB state." + required: false + type: string +rgb_state_topic: + description: The MQTT topic subscribed to receive RGB state updates. + required: false + type: string +rgb_value_template: + description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the RGB value." + required: false + type: string +state_topic: + description: The MQTT topic subscribed to receive state updates. + required: false + type: string +state_value_template: + description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the state value. The template should match the payload `on` and `off` values, so if your light uses `power on` to turn on, your `state_value_template` string should return `power on` when the switch is on. For example if the message is just `on`, your `state_value_template` should be `power {{ value }}`." + required: false + type: string +white_value_command_topic: + description: "The MQTT topic to publish commands to change the light's white value." + required: false + type: string +white_value_state_topic: + description: The MQTT topic subscribed to receive white value updates. + required: false + type: string +white_value_value_template: + description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the white value." + required: false + type: string +xy_command_topic: + description: "The MQTT topic to publish commands to change the light's XY state." + required: false + type: string +xy_state_topic: + description: The MQTT topic subscribed to receive XY state updates. + required: false + type: string +xy_value_template: + description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the XY value." + 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 +{% endconfiguration %}
Make sure that your topics match exactly. `some-topic/` and `some-topic` are different topics. diff --git a/source/_components/light.mqtt_json.markdown b/source/_components/light.mqtt_json.markdown index 54732fe5bff..d6ba5ad07d0 100644 --- a/source/_components/light.mqtt_json.markdown +++ b/source/_components/light.mqtt_json.markdown @@ -48,23 +48,94 @@ light: command_topic: "home/rgb1/set" ``` -Configuration variables: - -- **command_topic** (*Required*): The MQTT topic to publish commands to change the light's state. -- **brightness** (*Optional*): Flag that defines if the light supports brightness. Default is false. -- **color_temp** (*Optional*): Flag that defines if the light supports color temperature. Default is false. -- **effect** (*Optional*): Flag that defines if the light supports effects. Default is false. -- **effect_list** (*Optional*): The list of effects the light supports. -- **flash_time_long** (*Optional*): The duration, in seconds, of a "long" flash. Default is 10. -- **flash_time_short** (*Optional*): The duration, in seconds, of a "short" flash. Default is 2. -- **name** (*Optional*): The name of the light. Default is "MQTT JSON Light." -- **optimistic** (*Optional*): Flag that defines if the light works in optimistic mode. Default is true if no state topic defined, else false. -- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages. -- **retain** (*Optional*): If the published message should have the retain flag on or not. -- **rgb** (*Optional*): Flag that defines if the light supports RGB colors. Default is false. -- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates. -- **white_value** (*Optional*): Flag that defines if the light supports white values. Default is false. -- **xy** (*Optional*): Flag that defines if the light supports XY colors. Default is false. +{% configuration %} +name: + description: The name of the light. + required: false + type: string + default: MQTT JSON Light +command_topic: + description: The MQTT topic to publish commands to change the light’s state. + required: true + type: string +brightness: + description: Flag that defines if the light supports brightness. + required: false + type: boolean + default: false +color_temp: + description: Flag that defines if the light supports color temperature. + required: false + type: boolean + default: false +effect: + description: Flag that defines if the light supports effects. + required: false + type: boolean + default: false +effect_list: + description: The list of effects the light supports. + required: false + type: string list +flash_time_long: + description: The duration, in seconds, of a “long” flash. + required: false + type: integer + default: 10 +flash_time_short: + description: The duration, in seconds, of a “short” flash. + required: false + type: integer + default: 2 +optimistic: + description: Flag that defines if the light works in optimistic mode. + required: false + type: boolean + default: "`true` if no state topic defined, else `false`." +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 +rgb: + description: Flag that defines if the light supports RGB colors. + required: false + type: boolean + default: false +state_topic: + description: The MQTT topic subscribed to receive state updates. + required: false + type: string +white_value: + description: Flag that defines if the light supports white values. + required: false + type: boolean + default: false +xy: + description: Flag that defines if the light supports XY colors. + required: false + type: boolean + default: false +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 +{% endconfiguration %}
Make sure that your topics match exact. `some-topic/` and `some-topic` are different topics. diff --git a/source/_components/light.mqtt_template.markdown b/source/_components/light.mqtt_template.markdown index 3eed0fa3445..5a13ea9dfb6 100644 --- a/source/_components/light.mqtt_template.markdown +++ b/source/_components/light.mqtt_template.markdown @@ -33,24 +33,89 @@ light: command_off_template: "off" ``` -Configuration variables: - -- **name** (*Optional*): The name of the light. Default is "MQTT Template Light." -- **effect_list** (*Optional*): List of possible effects. -- **command_topic** (*Required*): The MQTT topic to publish commands to change the light's state. -- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates. -- **command_on_template** (*Required*): The [template](/docs/configuration/templating/#processing-incoming-data) for *on* state changes. Available variables: `state`, `brightness`, `red`, `green`, `blue`, `flash`, `transition` and `effect`. -- **command_off_template** (*Required*): The [template](/docs/configuration/templating/#processing-incoming-data) for *off* state changes. Available variables: `state` and `transition`. -- **state_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract state from the state payload value. -- **brightness_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract brightness from the state payload value. -- **red_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract red color from the state payload value. -- **green_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract green color from the state payload value. -- **blue_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract blue color from the state payload value. -- **color_temp_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract color temperature from the state payload value. -- **effect_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract effect from the state payload value. -- **white_value_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract white value from the state payload value. -- **optimistic** (*Optional*): Flag that defines if the light works in optimistic mode. Default is true if no state topic or state template is defined, else false. -- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages. +{% configuration %} +name: + description: The name of the light. + required: false + type: string + default: MQTT Template Light +effect_list: + description: List of possible effects. + required: false + type: string list +command_topic: + description: The MQTT topic to publish commands to change the light’s state. + required: true + type: string +state_topic: + description: The MQTT topic subscribed to receive state updates. + required: false + type: string +command_on_template: + description: "The [template](/docs/configuration/templating/#processing-incoming-data) for *on* state changes. Available variables: `state`, `brightness`, `red`, `green`, `blue`, `flash`, `transition` and `effect`." + required: true + type: string +command_off_template: + description: "The [template](/docs/configuration/templating/#processing-incoming-data) for *off* state changes. Available variables: `state` and `transition`." + required: true + type: string +state_template: + description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract state from the state payload value." + required: false + type: string +brightness_template: + description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract brightness from the state payload value." + required: false + type: string +red_template: + description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract red color from the state payload value." + required: false + type: string +green_template: + description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract green color from the state payload value." + required: false + type: string +blue_template: + description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract blue color from the state payload value." + required: false + type: string +color_temp_template: + description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract color temperature from the state payload value." + required: false + type: string +effect_template: + description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract effect from the state payload value." + required: false + type: string +white_value_template: + description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract white value from the state payload value." + required: false + type: string +optimistic: + description: Flag that defines if the light works in optimistic mode. + required: false + type: string + default: "`true` if no state topic or state template is defined, else `false`." +qos: + description: The maximum QoS level of the state topic. + required: false + type: integer + default: 0 +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 +{% endconfiguration %}
Make sure that your topics match exact. `some-topic/` and `some-topic` are different topics. diff --git a/source/_components/lock.mqtt.markdown b/source/_components/lock.mqtt.markdown index 6f91de7d133..8ed47ccf4ab 100644 --- a/source/_components/lock.mqtt.markdown +++ b/source/_components/lock.mqtt.markdown @@ -30,17 +30,64 @@ lock: command_topic: "home/frontdoor/set" ``` -Configuration variables: - -- **command_topic** (*Required*): The MQTT topic to publish commands to change the lock state. -- **name** (*Optional*): The name of the lock. Default is 'MQTT Lock'. -- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates. -- **payload_lock** (*Optional*): The payload that represents enabled/locked state. Default is "LOCK". -- **payload_unlock** (*Optional*): The payload that represents disabled/unlocked state. Default is "UNLOCK". -- **optimistic** (*Optional*): Flag that defines if lock works in optimistic mode. Default is `true` if no `state_topic` defined, else `false`. -- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages. -- **retain** (*Optional*): If the published message should have the retain flag on or not. -- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload. +{% configuration %} +name: + description: The name of the lock. + required: false + type: string + default: MQTT Lock +command_topic: + description: The MQTT topic to publish commands to change the lock state. + required: true + type: string +state_topic: + description: The MQTT topic subscribed to receive state updates. + required: false + type: string +payload_lock: + description: The payload that represents enabled/locked state. + required: false + type: string + default: LOCK +payload_unlock: + description: The payload that represents disabled/unlocked state. + required: false + type: string + default: UNLOCK +optimistic: + description: Flag that defines if lock works in optimistic mode. + required: false + type: string + default: "`true` if no `state_topic` defined, else `false`." +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 +value_template: + description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload." + 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 +{% endconfiguration %}
Make sure that your topics match exactly. `some-topic/` and `some-topic` are different topics. @@ -58,7 +105,7 @@ The example below shows a full configuration for a MQTT lock. # Example configuration.yml entry lock: - platform: mqtt - name: Frontdoor + name: Frontdoor state_topic: "home-assistant/frontdoor/" command_topic: "home-assistant/frontdoor/set" payload_lock: "LOCK" @@ -69,7 +116,7 @@ lock: value_template: '{% raw %}{{ value.x }}{% endraw %}' ``` -Keep an eye on retaining messages to keep the state as you don't want to unlock your door by accident when you restart something. +Keep an eye on retaining messages to keep the state as you don't want to unlock your door by accident when you restart something. For a check you can use the command line tools `mosquitto_pub` shipped with `mosquitto` to send MQTT messages. This allows you to operate your lock manually: diff --git a/source/_components/sensor.mqtt.markdown b/source/_components/sensor.mqtt.markdown index 0fb3ab1175f..9a7e6c00deb 100644 --- a/source/_components/sensor.mqtt.markdown +++ b/source/_components/sensor.mqtt.markdown @@ -58,8 +58,21 @@ force_update: reqired: false type: boolean default: False +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 {% endconfiguration %} - ## {% linkable_title Examples %} In this section you find some real life examples of how to use this sensor. diff --git a/source/_components/switch.mqtt.markdown b/source/_components/switch.mqtt.markdown index 4ad0a6c1f87..3804130cc61 100644 --- a/source/_components/switch.mqtt.markdown +++ b/source/_components/switch.mqtt.markdown @@ -30,20 +30,64 @@ switch: command_topic: "home/bedroom/switch1/set" ``` -Configuration variables: - -- **name** (*Optional*): The name of the switch. Default is 'MQTT Switch'. -- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates. -- **command_topic** (*Required*): The MQTT topic to publish commands to change the switch state. -- **availability_topic** (*Optional*): The MQTT topic subscribed to receive availability (online/offline) updates. -- **payload_on** (*Optional*): The payload that represents enabled state. Default is "ON". -- **payload_off** (*Optional*): The payload that represents disabled state. Default is "OFF". -- **payload_available** (*Optional*): The payload that represents the available state, e.g. 'online'. Default is "ON". -- **payload_not_available** (*Optional*): The payload that represents the unavailable state, e.g. 'offline'. Default is "OFF". -- **optimistic** (*Optional*): Flag that defines if switch works in optimistic mode. Default is `true` if no `state_topic` defined, else `false`. -- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages. -- **retain** (*Optional*): If the published message should have the retain flag on or not. -- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload. +{% configuration %} +name: + description: The name to use when displaying this switch. + required: false + type: string + default: MQTT Switch +state_topic: + description: The MQTT topic subscribed to receive state updates. + required: false + type: string +command_topic: + description: The MQTT topic to publish commands to change the switch state. + required: false + type: string +availability_topic: + description: The MQTT topic subscribed to receive availability (online/offline) updates. + required: false + type: string +payload_on: + description: The payload that represents enabled state. + required: false + type: string + default: ON +payload_off: + description: The payload that represents disabled state. + required: false + type: string + default: OFF +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 +optimistic: + description: Flag that defines if switch works in optimistic mode. + required: false + type: boolean + default: "`true` if no `state_topic` defined, else `false`." +qos: + description: The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages. + 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 +value_template: + description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload." + required: false + type: string +{% endconfiguration %}
Make sure that your topic matches exactly. `some-topic/` and `some-topic` are different topics. diff --git a/source/_components/vacuum.mqtt.markdown b/source/_components/vacuum.mqtt.markdown index df5a01a8cf8..65ed9679cef 100644 --- a/source/_components/vacuum.mqtt.markdown +++ b/source/_components/vacuum.mqtt.markdown @@ -53,36 +53,133 @@ vacuum: send_command_topic: 'vacuum/send_command' ``` -Basic Configuration variables: - -- **name** (*Optional*): The name of the vacuum. Defaults to `MQTT Vacuum`. -- **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`. -- **command_topic** (*Optional*): The MQTT topic to publish commands to control the vacuum. - -Advanced Configuration variables: - -- **qos** (*Optional*): The maximum QoS level of the state topic. Defaults to `0`. Will also be used when publishing messages. -- **retain** (*Optional*): If the published message should have the retain flag on or not. Defaults to `false`. -- **payload_turn_on** (*Optional*): The payload to send to the `command_topic` to begin the cleaning cycle. Defaults to `turn_on`. -- **payload_turn_off** (*Optional*): The payload to send to the `command_topic` to turn the vacuum off. Defaults to `turn_off`. -- **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`. -- **payload_stop** (*Optional*): The payload to send to the `command_topic` to stop the vacuum. Defaults to `stop`. -- **payload_clean_spot** (*Optional*): The payload to send to the `command_topic` to begin a spot cleaning cycle. Defaults to `clean_spot`. -- **payload_locate** (*Optional*): The payload to send to the `command_topic` to locate the vacuum (typically plays a song). Defaults to `locate`. -- **payload_start_pause** (*Optional*): The payload to send to the `command_topic` to start or pause the vacuum. Defaults to `start_pause`. -- **battery_level_topic** (*Optional*): The MQTT topic subscribed to receive battery level values from the vacuum. -- **battery_level_template** (*Optional*): Defines a [template](/topics/templating/) to define the battery level of the vacuum. -- **charging_topic** (*Optional*): The MQTT topic subscribed to receive charging state values from the vacuum. -- **charging_template** (*Optional*): Defines a [template](/topics/templating/) to define the charging state of the vacuum. -- **cleaning_topic** (*Optional*): The MQTT topic subscribed to receive cleaning state values from the vacuum. -- **cleaning_template** (*Optional*): Defines a [template](/topics/templating/) to define the cleaning state of the vacuum. -- **docked_topic** (*Optional*): The MQTT topic subscribed to receive docked state values from the vacuum. -- **docked_template** (*Optional*): Defines a [template](/topics/templating/) to define the docked state of the vacuum. -- **fan_speed_topic** (*Optional*): The MQTT topic subscribed to receive fan speed values from the vacuum. -- **fan_speed_template** (*Optional*): Defines a [template](/topics/templating/) to define the fan speed of the vacuum. -- **set_fan_speed_topic** (*Optional*): The MQTT topic to publish commands to control the vacuum's fan speed. -- **fan_speed_list** (*Optional*): List of possible fan speeds for the vacuum. -- **send_command_topic** (*Optional*): The MQTT topic to publish custom commands to the vacuum. +{% configuration %} +name: + description: The name of the vacuum. + required: false + type: string + default: MQTT Vacuum +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`" +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_turn_on: + description: "The payload to send to the `command_topic` to begin the cleaning cycle." + required: false + type: string + default: turn_on +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_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_stop: + description: The payload to send to the `command_topic` to stop the vacuum. + required: false + type: string + default: stop +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_start_pause: + description: The payload to send to the `command_topic` to start or pause the vacuum. + required: false + type: string + default: start_pause +battery_level_topic: + description: The MQTT topic subscribed to receive battery level values from the vacuum. + required: false + type: string +battery_level_template: + description: "Defines a [template](/topics/templating/) to define the battery level of the vacuum." + required: false + type: string +charging_topic: + description: The MQTT topic subscribed to receive charging state values from the vacuum. + required: false + type: string +charging_template: + description: "Defines a [template](/topics/templating/) to define the charging state of the vacuum." + required: false + type: string +cleaning_topic: + description: The MQTT topic subscribed to receive cleaning state values from the vacuum. + required: false + type: string +cleaning_template: + description: "Defines a [template](/topics/templating/) to define the cleaning state of the vacuum." + required: false + type: string +docked_topic: + description: The MQTT topic subscribed to receive docked state values from the vacuum. + required: false + type: string +docked_template: + description: "Defines a [template](/topics/templating/) to define the docked state of the vacuum." + required: false + type: string +fan_speed_topic: + description: The MQTT topic subscribed to receive fan speed values from the vacuum. + required: false + type: string +fan_speed_template: + description: "Defines a [template](/topics/templating/) to define the fan speed of 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 +{% endconfiguration %} ### {% linkable_title Default MQTT Protocol %}