jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-23 17:27:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Sort MQTT config (#12199)

Browse Source
This commit is contained in:
Erik Montnemery 2020-02-28 15:52:41 +01:00 committed by GitHub
parent a985a2ba89
commit 1dc5a07ba8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 1269 additions and 1277 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

144
source/_integrations/alarm_control_panel.mqtt.markdown
View File

@ -34,57 +34,10 @@ alarm_control_panel:
```
{% configuration %}
name:
description: The name of the alarm.
availability_topic:
description: The MQTT topic subscribed to receive availability (online/offline) updates.
required: false
type: string
default: MQTT Alarm
unique_id:
description: An ID that uniquely identifies this alarm panel. If two alarm panels have the same unique ID, Home Assistant will raise an exception.
required: false
type: string
state_topic:
description: The MQTT topic subscribed to receive state updates.
required: true
type: string
command_topic:
description: The MQTT topic to publish commands to change the alarm state.
required: true
type: string
command_template:
description: "The [template](/docs/configuration/templating/#processing-incoming-data) used for the command payload. Available variables: `action` and `code`."
required: false
type: string
default: action
value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the value."
required: false
type: template
qos:
description: The maximum QoS level of the state topic.
required: false
type: integer
default: 0
payload_disarm:
description: The payload to disarm your Alarm Panel.
required: false
type: string
default: DISARM
payload_arm_home:
description: The payload to set armed-home mode on your Alarm Panel.
required: false
type: string
default: ARM_HOME
payload_arm_away:
description: The payload to set armed-away mode on your Alarm Panel.
required: false
type: string
default: ARM_AWAY
payload_arm_night:
description: The payload to set armed-night mode on your Alarm Panel.
required: false
type: string
default: ARM_NIGHT
code:
description: If defined, specifies a code to enable or disable the alarm in the frontend.
required: false
@ -99,41 +52,28 @@ code_disarm_required:
required: false
type: boolean
default: true
availability_topic:
description: The MQTT topic subscribed to receive availability (online/offline) updates.
command_template:
description: "The [template](/docs/configuration/templating/#processing-incoming-data) used for the command payload. Available variables: `action` and `code`."
required: false
type: string
payload_available:
description: The payload that represents the available state.
required: false
default: action
command_topic:
description: The MQTT topic to publish commands to change the alarm state.
required: true
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](/integrations/sensor.mqtt/#json-attributes-topic-configuration) documentation.
required: false
type: string
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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
device:
description: 'Information about the device this alarm panel is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set.'
required: false
type: map
keys:
identifiers:
description: 'A list of IDs that uniquely identify the device. For example a serial number.'
required: false
type: [list, string]
connections:
description: 'A list of connections of the device to the outside world as a list of tuples `[connection_type, connection_identifier]`. For example the MAC address of a network interface: `"connections": [["mac", "02:5b:26:a8:dc:12"]]`.'
required: false
type: list
identifiers:
description: 'A list of IDs that uniquely identify the device. For example a serial number.'
required: false
type: [list, string]
manufacturer:
description: 'The manufacturer of the device.'
required: false
@ -150,4 +90,64 @@ device:
description: 'The firmware version of the device.'
required: false
type: string
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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 alarm.
required: false
type: string
default: MQTT Alarm
payload_arm_away:
description: The payload to set armed-away mode on your Alarm Panel.
required: false
type: string
default: ARM_AWAY
payload_arm_home:
description: The payload to set armed-home mode on your Alarm Panel.
required: false
type: string
default: ARM_HOME
payload_arm_night:
description: The payload to set armed-night mode on your Alarm Panel.
required: false
type: string
default: ARM_NIGHT
payload_available:
description: The payload that represents the available state.
required: false
type: string
default: online
payload_disarm:
description: The payload to disarm your Alarm Panel.
required: false
type: string
default: DISARM
payload_not_available:
description: The payload that represents the unavailable state.
required: false
type: string
default: offline
qos:
description: The maximum QoS level of the state topic.
required: false
type: integer
default: 0
state_topic:
description: The MQTT topic subscribed to receive state updates.
required: true
type: string
unique_id:
description: An ID that uniquely identifies this alarm panel. If two alarm panels have the same unique ID, Home Assistant will raise an exception.
required: false
type: string
value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the value."
required: false
type: template
{% endconfiguration %}

142
source/_integrations/binary_sensor.mqtt.markdown
View File

@ -32,90 +32,23 @@ binary_sensor:
```
{% configuration %}
state_topic:
description: The MQTT topic subscribed to receive sensor values.
required: true
type: string
name:
description: The name of the binary sensor.
required: false
type: string
default: MQTT Binary Sensor
payload_on:
description: The payload that represents the on state.
required: false
type: string
default: "ON"
payload_off:
description: The payload that represents the off state.
required: false
type: string
default: "OFF"
availability_topic:
description: "The MQTT topic subscribed to receive birth and LWT messages from the MQTT device. If `availability_topic` is not defined, the binary sensor availability state will always be `available`. If `availability_topic` is defined, the binary sensor availability state will be `unavailable` by default."
required: false
type: string
payload_available:
description: The payload that represents the online state.
required: false
type: string
default: online
payload_not_available:
description: The payload that represents the offline 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](/integrations/sensor.mqtt/#json-attributes-topic-configuration) documentation.
required: false
type: string
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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
qos:
description: The maximum QoS level to be used when receiving messages.
required: false
type: integer
default: 0
unique_id:
description: An ID that uniquely identifies this sensor. If two sensors have the same unique ID, Home Assistant will raise an exception.
required: false
type: string
device_class:
description: Sets the [class of the device](/integrations/binary_sensor/#device-class), changing the device state and icon that is displayed on the frontend.
required: false
type: string
expire_after:
description: "Defines the number of seconds after the value expires if it's not updated. After expiry, the value is cleared, and the availability is set to false"
required: false
type: integer
value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload. Available variables: `entity_id`. Remove this option when 'payload_on' and 'payload_off' are sufficient to match your payloads."
required: false
type: string
force_update:
description: Sends update events even if the value hasn't changed. Useful if you want to have meaningful value graphs in history.
required: false
type: boolean
default: false
off_delay:
description: "For sensors that only sends `On` state updates, this variable sets a delay in seconds after which the sensor state will be updated back to `Off`."
required: false
type: integer
device:
description: "Information about the device this binary sensor is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set."
required: false
type: map
keys:
identifiers:
description: A list of IDs that uniquely identify the device. For example a serial number.
required: false
type: [list, string]
connections:
description: "A list of connections of the device to the outside world as a list of tuples `[connection_type, connection_identifier]`. For example the MAC address of a network interface: `'connections': ['mac', '02:5b:26:a8:dc:12']`."
required: false
type: [list, map]
identifiers:
description: A list of IDs that uniquely identify the device. For example a serial number.
required: false
type: [list, string]
manufacturer:
description: The manufacturer of the device.
required: false
@ -132,6 +65,73 @@ device:
description: The firmware version of the device.
required: false
type: string
device_class:
description: Sets the [class of the device](/integrations/binary_sensor/#device-class), changing the device state and icon that is displayed on the frontend.
required: false
type: string
expire_after:
description: "Defines the number of seconds after the value expires if it's not updated. After expiry, the value is cleared, and the availability is set to false"
required: false
type: integer
force_update:
description: Sends update events even if the value hasn't changed. Useful if you want to have meaningful value graphs in history.
required: false
type: boolean
default: false
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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 binary sensor.
required: false
type: string
default: MQTT Binary Sensor
off_delay:
description: "For sensors that only sends `On` state updates, this variable sets a delay in seconds after which the sensor state will be updated back to `Off`."
required: false
type: integer
payload_available:
description: The payload that represents the online state.
required: false
type: string
default: online
payload_not_available:
description: The payload that represents the offline state.
required: false
type: string
default: offline
payload_off:
description: The payload that represents the off state.
required: false
type: string
default: "OFF"
payload_on:
description: The payload that represents the on state.
required: false
type: string
default: "ON"
qos:
description: The maximum QoS level to be used when receiving messages.
required: false
type: integer
default: 0
state_topic:
description: The MQTT topic subscribed to receive sensor values.
required: true
type: string
unique_id:
description: An ID that uniquely identifies this sensor. If two sensors have the same unique ID, Home Assistant will raise an exception.
required: false
type: string
value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload. Available variables: `entity_id`. Remove this option when 'payload_on' and 'payload_off' are sufficient to match your payloads."
required: false
type: string
{% endconfiguration %}
## Examples

32
source/_integrations/camera.mqtt.markdown
View File

@ -24,31 +24,19 @@ camera:
```
{% configuration %}
topic:
description: The MQTT topic to subscribe to.
required: true
type: string
name:
description: The name of the camera.
required: false
type: string
unique_id:
description: An ID that uniquely identifies this camera. If two cameras have the same unique ID Home Assistant will raise an exception.
required: false
type: string
device:
description: "Information about the device this camera is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set."
required: false
type: map
keys:
identifiers:
description: 'A list of IDs that uniquely identify the device. For example a serial number.'
required: false
type: [list, string]
connections:
description: 'A list of connections of the device to the outside world as a list of tuples `[connection_type, connection_identifier]`. For example the MAC address of a network interface: `"connections": ["mac", "02:5b:26:a8:dc:12"]`.'
required: false
type: list
identifiers:
description: 'A list of IDs that uniquely identify the device. For example a serial number.'
required: false
type: [list, string]
manufacturer:
description: The manufacturer of the device.
required: false
@ -65,4 +53,16 @@ device:
description: The firmware version of the device.
required: false
type: string
name:
description: The name of the camera.
required: false
type: string
topic:
description: The MQTT topic to subscribe to.
required: true
type: string
unique_id:
description: An ID that uniquely identifies this camera. If two cameras have the same unique ID Home Assistant will raise an exception.
required: false
type: string
{% endconfiguration %}

440
source/_integrations/climate.mqtt.markdown
View File

@ -21,259 +21,65 @@ climate:
```
{% configuration %}
name:
description: The name of the HVAC.
required: false
type: string
default: MQTT HVAC
unique_id:
description: An ID that uniquely identifies this HVAC device. If two HVAC devices have the same unique ID, Home Assistant will raise an exception.
required: false
type: string
qos:
description: The maximum QoS level to be used when receiving and publishing messages.
required: false
type: integer
default: 0
retain:
description: Defines if published messages should have the retain flag set.
required: false
type: boolean
default: false
send_if_off:
description: "Set to `false` to suppress sending of all MQTT messages when the current mode is `Off`."
required: false
type: boolean
default: true
initial:
description: Set the initial target temperature.
required: false
type: integer
default: 21
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"
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
value_template:
description: Default template to render the payloads on *all* `*_state_topic`s with.
type: template
required: false
current_temperature_topic:
description: The MQTT topic on which to listen for the current temperature.
required: false
type: string
current_temperature_template:
description: A template with which the value received on `current_temperature_topic` will be rendered.
action_template:
description: A template to render the value received on the `action_topic` with.
required: false
type: template
power_command_topic:
description: The MQTT topic to publish commands to change the power state. This is useful if your device has a separate power toggle in addition to mode.
required: false
type: string
action_topic:
description: >-
The MQTT topic to subscribe for changes of the current action. If this is set, the climate graph uses the value received as data source.
Valid values: `off`, `heating`, `cooling`, `drying`, `idle`, `fan`.
required: false
type: string
action_template:
description: A template to render the value received on the `action_topic` with.
required: false
type: template
mode_command_topic:
description: The MQTT topic to publish commands to change the HVAC operation mode.
required: false
type: string
mode_state_topic:
description: The MQTT topic to subscribe for changes of the HVAC operation mode. If this is not set, the operation mode works in optimistic mode (see below).
required: false
type: string
mode_state_template:
description: A template to render the value received on the `mode_state_topic` with.
required: false
type: template
modes:
description: A list of supported modes. Needs to be a subset of the default values.
required: false
default: ['auto', 'off', 'cool', 'heat', 'dry', 'fan_only']
type: list
action_topic:
description: The MQTT topic on which to listen for the current action state of the HVAC. Expects `idle`, `cooling`, `heating`, `drying`, or `off`.
required: false
type: string
action_template:
description: A template to render the value received on the `action_topic` with.
required: false
type: template
temperature_command_topic:
description: The MQTT topic to publish commands to change the target temperature.
required: false
type: string
temperature_state_topic:
description: The MQTT topic to subscribe for changes in the target temperature. If this is not set, the target temperature works in optimistic mode (see below).
required: false
type: string
temperature_state_template:
description: A template to render the value received on the `temperature_state_topic` with.
required: false
type: template
temperature_low_command_topic:
description: The MQTT topic to publish commands to change the target low temperature.
required: false
type: string
temperature_low_state_topic:
description: The MQTT topic to subscribe for changes in the target low temperature. If this is not set, the target low temperature works in optimistic mode (see below).
required: false
type: string
temperature_low_state_template:
description: A template to render the value received on the `temperature_low_state_topic` with.
required: false
type: template
temperature_high_command_topic:
description: The MQTT topic to publish commands to change the high target temperature.
required: false
type: string
temperature_high_state_topic:
description: The MQTT topic to subscribe for changes in the target high temperature. If this is not set, the target high temperature works in optimistic mode (see below).
required: false
type: string
temperature_high_state_template:
description: A template to render the value received on the `temperature_high_state_topic` with.
required: false
type: template
precision:
description: The desired precision for this device. Can be used to match your actual thermostat's precision. Supported values are `0.1`, `0.5` and `1.0`.
required: false
type: float
default: 0.1 for Celsius and 1.0 for Fahrenheit.
fan_mode_command_topic:
description: The MQTT topic to publish commands to change the fan mode.
required: false
type: string
fan_mode_state_topic:
description: The MQTT topic to subscribe for changes of the HVAC fan mode. If this is not set, the fan mode works in optimistic mode (see below).
required: false
type: string
fan_mode_state_template:
description: A template to render the value received on the `fan_mode_state_topic` with.
required: false
type: template
fan_modes:
description: A list of supported fan modes.
required: false
default: ['auto', 'low', 'medium', 'high']
type: list
swing_mode_command_topic:
description: The MQTT topic to publish commands to change the swing mode.
required: false
type: string
swing_mode_state_topic:
description: The MQTT topic to subscribe for changes of the HVAC swing mode. If this is not set, the swing mode works in optimistic mode (see below).
required: false
type: string
swing_mode_state_template:
description: A template to render the value received on the `swing_mode_state_topic` with.
required: false
type: template
swing_modes:
description: A list of supported swing modes.
required: false
default: ['on', 'off']
type: list
away_mode_command_topic:
description: The MQTT topic to publish commands to change the away mode.
required: false
type: string
away_mode_state_topic:
description: The MQTT topic to subscribe for changes of the HVAC away mode. If this is not set, the away mode works in optimistic mode (see below).
required: false
type: string
away_mode_state_template:
description: A template to render the value received on the `away_mode_state_topic` with.
required: false
type: template
hold_command_topic:
description: The MQTT topic to publish commands to change the hold mode.
required: false
type: string
hold_state_topic:
description: The MQTT topic to subscribe for changes of the HVAC hold mode. If this is not set, the hold mode works in optimistic mode (see below).
required: false
type: string
hold_state_template:
description: A template to render the value received on the `hold_state_topic` with.
required: false
type: template
hold_modes:
description: A list of available hold modes.
required: false
type: list
aux_command_topic:
description: The MQTT topic to publish commands to switch auxiliary heat.
required: false
type: string
aux_state_topic:
description: The MQTT topic to subscribe for changes of the auxiliary heat mode. If this is not set, the auxiliary heat mode works in optimistic mode (see below).
required: false
type: string
aux_state_template:
description: A template to render the value received on the `aux_state_topic` with.
required: false
type: template
min_temp:
description: Minimum set point available.
type: float
required: false
max_temp:
description: Maximum set point available.
type: float
required: false
temp_step:
description: Step size for temperature set point.
type: float
required: false
default: 1
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.
aux_state_topic:
description: The MQTT topic to subscribe for changes of the auxiliary heat mode. If this is not set, the auxiliary heat mode works in optimistic mode (see below).
required: false
type: string
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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."
availability_topic:
description: The MQTT topic subscribed to receive availability (online/offline) updates.
required: false
type: string
away_mode_command_topic:
description: The MQTT topic to publish commands to change the away mode.
required: false
type: string
away_mode_state_template:
description: A template to render the value received on the `away_mode_state_topic` with.
required: false
type: template
away_mode_state_topic:
description: The MQTT topic to subscribe for changes of the HVAC away mode. If this is not set, the away mode works in optimistic mode (see below).
required: false
type: string
current_temperature_template:
description: A template with which the value received on `current_temperature_topic` will be rendered.
required: false
type: template
current_temperature_topic:
description: The MQTT topic on which to listen for the current temperature.
required: false
type: string
device:
description: 'Information about the device this HVAC device is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set.'
required: false
type: map
keys:
identifiers:
description: 'A list of IDs that uniquely identify the device. For example a serial number.'
required: false
type: [list, string]
connections:
description: 'A list of connections of the device to the outside world as a list of tuples `[connection_type, connection_identifier]`. For example the MAC address of a network interface: `"connections": [["mac", "02:5b:26:a8:dc:12"]]`.'
required: false
type: list
identifiers:
description: 'A list of IDs that uniquely identify the device. For example a serial number.'
required: false
type: [list, string]
manufacturer:
description: 'The manufacturer of the device.'
required: false
@ -290,6 +96,192 @@ device:
description: 'The firmware version of the device.'
required: false
type: string
fan_mode_command_topic:
description: The MQTT topic to publish commands to change the fan mode.
required: false
type: string
fan_mode_state_template:
description: A template to render the value received on the `fan_mode_state_topic` with.
required: false
type: template
fan_mode_state_topic:
description: The MQTT topic to subscribe for changes of the HVAC fan mode. If this is not set, the fan mode works in optimistic mode (see below).
required: false
type: string
fan_modes:
description: A list of supported fan modes.
required: false
default: ['auto', 'low', 'medium', 'high']
type: list
hold_command_topic:
description: The MQTT topic to publish commands to change the hold mode.
required: false
type: string
hold_state_template:
description: A template to render the value received on the `hold_state_topic` with.
required: false
type: template
hold_state_topic:
description: The MQTT topic to subscribe for changes of the HVAC hold mode. If this is not set, the hold mode works in optimistic mode (see below).
required: false
type: string
hold_modes:
description: A list of available hold modes.
required: false
type: list
initial:
description: Set the initial target temperature.
required: false
type: integer
default: 21
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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
max_temp:
description: Maximum set point available.
type: float
required: false
min_temp:
description: Minimum set point available.
type: float
required: false
mode_command_topic:
description: The MQTT topic to publish commands to change the HVAC operation mode.
required: false
type: string
mode_state_template:
description: A template to render the value received on the `mode_state_topic` with.
required: false
type: template
mode_state_topic:
description: The MQTT topic to subscribe for changes of the HVAC operation mode. If this is not set, the operation mode works in optimistic mode (see below).
required: false
type: string
modes:
description: A list of supported modes. Needs to be a subset of the default values.
required: false
default: ['auto', 'off', 'cool', 'heat', 'dry', 'fan_only']
type: list
name:
description: The name of the HVAC.
required: false
type: string
default: MQTT HVAC
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
payload_off:
description: The payload that represents disabled state.
required: false
type: string
default: "OFF"
payload_on:
description: The payload that represents enabled state.
required: false
type: string
default: "ON"
power_command_topic:
description: The MQTT topic to publish commands to change the power state. This is useful if your device has a separate power toggle in addition to mode.
required: false
type: string
precision:
description: The desired precision for this device. Can be used to match your actual thermostat's precision. Supported values are `0.1`, `0.5` and `1.0`.
required: false
type: float
default: 0.1 for Celsius and 1.0 for Fahrenheit.
qos:
description: The maximum QoS level to be used when receiving and publishing messages.
required: false
type: integer
default: 0
retain:
description: Defines if published messages should have the retain flag set.
required: false
type: boolean
default: false
send_if_off:
description: "Set to `false` to suppress sending of all MQTT messages when the current mode is `Off`."
required: false
type: boolean
default: true
swing_mode_command_topic:
description: The MQTT topic to publish commands to change the swing mode.
required: false
type: string
swing_mode_state_template:
description: A template to render the value received on the `swing_mode_state_topic` with.
required: false
type: template
swing_mode_state_topic:
description: The MQTT topic to subscribe for changes of the HVAC swing mode. If this is not set, the swing mode works in optimistic mode (see below).
required: false
type: string
swing_modes:
description: A list of supported swing modes.
required: false
default: ['on', 'off']
type: list
temperature_command_topic:
description: The MQTT topic to publish commands to change the target temperature.
required: false
type: string
temperature_high_command_topic:
description: The MQTT topic to publish commands to change the high target temperature.
required: false
type: string
temperature_high_state_template:
description: A template to render the value received on the `temperature_high_state_topic` with.
required: false
type: template
temperature_high_state_topic:
description: The MQTT topic to subscribe for changes in the target high temperature. If this is not set, the target high temperature works in optimistic mode (see below).
required: false
type: string
temperature_low_command_topic:
description: The MQTT topic to publish commands to change the target low temperature.
required: false
type: string
temperature_low_state_template:
description: A template to render the value received on the `temperature_low_state_topic` with.
required: false
type: template
temperature_low_state_topic:
description: The MQTT topic to subscribe for changes in the target low temperature. If this is not set, the target low temperature works in optimistic mode (see below).
required: false
type: string
temperature_state_template:
description: A template to render the value received on the `temperature_state_topic` with.
required: false
type: template
temperature_state_topic:
description: The MQTT topic to subscribe for changes in the target temperature. If this is not set, the target temperature works in optimistic mode (see below).
required: false
type: string
temp_step:
description: Step size for temperature set point.
type: float
required: false
default: 1
unique_id:
description: An ID that uniquely identifies this HVAC device. If two HVAC devices have the same unique ID, Home Assistant will raise an exception.
required: false
type: string
value_template:
description: Default template to render the payloads on *all* `*_state_topic`s with.
type: template
required: false
{% endconfiguration %}
#### Optimistic mode

318
source/_integrations/cover.mqtt.markdown
View File

@ -37,165 +37,12 @@ cover:
```
{% configuration %}
command_topic:
description: The MQTT topic to publish commands to control the cover.
required: false
type: string
name:
description: The name of the cover.
required: false
type: string
default: MQTT Cover
payload_open:
description: The command payload that opens the cover.
required: false
type: string
default: OPEN
payload_close:
description: The command payload that closes the cover.
required: false
type: string
default: CLOSE
payload_stop:
description: The command payload that stops the cover.
required: false
type: string
default: STOP
state_topic:
description: The MQTT topic subscribed to receive cover state messages. Use only if not using `position_topic`. State topic can only read open/close state. Cannot read position state. If `position_topic` is set `state_topic` is ignored.
required: false
type: string
state_open:
description: The payload that represents the open state.
required: false
type: string
default: open
state_opening:
description: The payload that represents the opening state.
required: false
type: string
default: opening
state_closed:
description: The payload that represents the closed state.
required: false
type: string
default: closed
state_closing:
description: The payload that represents the closing state.
required: false
type: string
default: closing
position_topic:
description: The MQTT topic subscribed to receive cover position messages. If `position_topic` is set `state_topic` is ignored.
required: false
type: string
position_open:
description: Number which represents open position.
required: false
type: integer
default: 100
position_closed:
description: Number which represents closed position.
required: false
type: integer
default: 0
availability_topic:
description: "The MQTT topic subscribed to to receive birth and LWT messages from the MQTT cover device. If `availability_topic` is not defined, the cover availability state will always be `available`. If `availability_topic` is defined, the cover availability state will be `unavailable` by default."
required: false
type: string
payload_available:
description: The payload that represents the online state.
required: false
type: string
default: online
payload_not_available:
description: The payload that represents the offline state.
required: false
type: string
default: offline
optimistic:
description: Flag that defines if switch works in optimistic mode.
required: false
type: string
default: "`true` if no state topic defined, else `false`."
qos:
description: The maximum QoS level to be used when receiving and publishing messages.
required: false
type: integer
default: 0
retain:
description: Defines if published messages should have the retain flag set.
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
set_position_topic:
description: "The MQTT topic to publish position commands to. You need to set position_topic as well if you want to use position topic. Use template if position topic wants different values than within range `position_closed` - `position_open`. If template is not defined and `position_closed != 100` and `position_open != 0` then proper position value is calculated from percentage position."
required: false
type: string
set_position_template:
description: "Defines a [template](/topics/templating/) to define the position to be sent to the `set_position_topic` topic. Incoming position value is available for use in the template `{{position}}`. If no template is defined, the position (0-100) will be calculated according to `position_open` and `position_closed` values."
required: false
type: string
tilt_command_topic:
description: The MQTT topic to publish commands to control the cover tilt.
required: false
type: string
tilt_status_topic:
description: The MQTT topic subscribed to receive tilt status update values.
required: false
type: string
tilt_status_template:
description: "Defines a [template](/topics/templating/) that can be used to extract the payload for the `tilt_status_topic` topic. "
required: false
type: string
tilt_min:
description: The minimum tilt value.
required: false
type: integer
default: 0
tilt_max:
description: The maximum tilt value
required: false
type: integer
default: 100
tilt_closed_value:
description: The value that will be sent on a `close_cover_tilt` command.
required: false
type: integer
default: 0
tilt_opened_value:
description: The value that will be sent on an `open_cover_tilt` command.
required: false
type: integer
default: 100
tilt_optimistic:
description: Flag that determines if tilt works in optimistic mode.
required: false
type: boolean
default: "`true` if `tilt_status_topic` is not defined, else `false`"
tilt_invert_state:
description: Flag that determines if open/close are flipped; higher values toward closed and lower values toward open.
required: false
type: boolean
default: false
device_class:
description: Sets the [class of the device](/integrations/cover/), changing the device state and icon that is displayed on the frontend.
required: false
type: string
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
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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
unique_id:
description: An ID that uniquely identifies this cover. If two covers have the same unique ID, Home Assistant will raise an exception.
command_topic:
description: The MQTT topic to publish commands to control the cover.
required: false
type: string
device:
@ -203,14 +50,14 @@ device:
required: false
type: map
keys:
identifiers:
description: 'A list of IDs that uniquely identify the device. For example a serial number.'
required: false
type: [list, string]
connections:
description: 'A list of connections of the device to the outside world as a list of tuples `[connection_type, connection_identifier]`. For example the MAC address of a network interface: `"connections": ["mac", "02:5b:26:a8:dc:12"]`.'
required: false
type: list
identifiers:
description: 'A list of IDs that uniquely identify the device. For example a serial number.'
required: false
type: [list, string]
manufacturer:
description: The manufacturer of the device.
required: false
@ -227,6 +74,159 @@ device:
description: The firmware version of the device.
required: false
type: string
device_class:
description: Sets the [class of the device](/integrations/cover/), changing the device state and icon that is displayed on the frontend.
required: false
type: string
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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 cover.
required: false
type: string
default: MQTT Cover
optimistic:
description: Flag that defines if switch works in optimistic mode.
required: false
type: string
default: "`true` if no state topic defined, else `false`."
payload_available:
description: The payload that represents the online state.
required: false
type: string
default: online
payload_close:
description: The command payload that closes the cover.
required: false
type: string
default: CLOSE
payload_not_available:
description: The payload that represents the offline state.
required: false
type: string
default: offline
payload_open:
description: The command payload that opens the cover.
required: false
type: string
default: OPEN
payload_stop:
description: The command payload that stops the cover.
required: false
type: string
default: STOP
position_closed:
description: Number which represents closed position.
required: false
type: integer
default: 0
position_open:
description: Number which represents open position.
required: false
type: integer
default: 100
position_topic:
description: The MQTT topic subscribed to receive cover position messages. If `position_topic` is set `state_topic` is ignored.
required: false
type: string
qos:
description: The maximum QoS level to be used when receiving and publishing messages.
required: false
type: integer
default: 0
retain:
description: Defines if published messages should have the retain flag set.
required: false
type: boolean
default: false
set_position_template:
description: "Defines a [template](/topics/templating/) to define the position to be sent to the `set_position_topic` topic. Incoming position value is available for use in the template `{{position}}`. If no template is defined, the position (0-100) will be calculated according to `position_open` and `position_closed` values."
required: false
type: string
set_position_topic:
description: "The MQTT topic to publish position commands to. You need to set position_topic as well if you want to use position topic. Use template if position topic wants different values than within range `position_closed` - `position_open`. If template is not defined and `position_closed != 100` and `position_open != 0` then proper position value is calculated from percentage position."
required: false
type: string
state_closed:
description: The payload that represents the closed state.
required: false
type: string
default: closed
state_closing:
description: The payload that represents the closing state.
required: false
type: string
default: closing
state_open:
description: The payload that represents the open state.
required: false
type: string
default: open
state_opening:
description: The payload that represents the opening state.
required: false
type: string
default: opening
state_topic:
description: The MQTT topic subscribed to receive cover state messages. Use only if not using `position_topic`. State topic can only read open/close state. Cannot read position state. If `position_topic` is set `state_topic` is ignored.
required: false
type: string
tilt_closed_value:
description: The value that will be sent on a `close_cover_tilt` command.
required: false
type: integer
default: 0
tilt_command_topic:
description: The MQTT topic to publish commands to control the cover tilt.
required: false
type: string
tilt_invert_state:
description: Flag that determines if open/close are flipped; higher values toward closed and lower values toward open.
required: false
type: boolean
default: false
tilt_max:
description: The maximum tilt value
required: false
type: integer
default: 100
tilt_min:
description: The minimum tilt value.
required: false
type: integer
default: 0
tilt_opened_value:
description: The value that will be sent on an `open_cover_tilt` command.
required: false
type: integer
default: 100
tilt_optimistic:
description: Flag that determines if tilt works in optimistic mode.
required: false
type: boolean
default: "`true` if `tilt_status_topic` is not defined, else `false`"
tilt_status_template:
description: "Defines a [template](/topics/templating/) that can be used to extract the payload for the `tilt_status_topic` topic. "
required: false
type: string
tilt_status_topic:
description: The MQTT topic subscribed to receive tilt status update values.
required: false
type: string
unique_id:
description: An ID that uniquely identifies this cover. If two covers have the same unique ID, Home Assistant will raise an exception.
required: false
type: string
value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload."
required: false
type: string
{% endconfiguration %}
## Examples

240
source/_integrations/fan.mqtt.markdown
View File

@ -28,140 +28,27 @@ fan:
```
{% configuration %}
command_topic:
description: The MQTT topic to publish commands to change the fan state.
required: true
type: string
name:
description: The name of the fan.
required: false
type: string
default: MQTT Fan
state_topic:
description: The MQTT topic subscribed to receive state updates.
required: false
type: string
payload_on:
description: The payload that represents the running state.
required: false
type: string
default: "ON"
payload_off:
description: The payload that represents the stop state.
required: false
type: string
default: "OFF"
state_value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the state."
required: false
type: string
qos:
description: The maximum QoS level of the state topic.
required: false
type: integer
default: 0
optimistic:
description: Flag that defines if lock works in optimistic mode
required: false
type: boolean
default: "`true` if no state topic defined, else `false`."
retain:
description: If the published message should have the retain flag on or not.
required: false
type: boolean
default: true
oscillation_state_topic:
description: The MQTT topic subscribed to receive oscillation state updates.
required: false
type: string
oscillation_command_topic:
description: The MQTT topic to publish commands to change the oscillation state.
required: false
type: string
payload_oscillation_on:
description: The payload that represents the oscillation on state.
required: false
type: string
default: oscillate_on
payload_oscillation_off:
description: The payload that represents the oscillation off state.
required: false
type: string
default: oscillate_off
oscillation_value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the oscillation."
required: false
type: string
speed_state_topic:
description: The MQTT topic subscribed to receive speed state updates.
required: false
type: string
speed_command_topic:
description: The MQTT topic to publish commands to change speed state.
required: false
type: string
payload_low_speed:
description: The payload that represents the fan's low speed.
required: false
type: string
default: low
payload_medium_speed:
description: The payload that represents the fan's medium speed.
required: false
type: string
default: medium
payload_high_speed:
description: The payload that represents the fan's high speed.
required: false
type: string
default: high
speed_value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the speed payload."
required: false
type: string
speeds:
description: "List of speeds this fan is capable of running at. Valid entries are `off`, `low`, `medium` and `high`."
required: false
type: [string, list]
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](/integrations/sensor.mqtt/#json-attributes-topic-configuration) documentation.
required: false
type: string
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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
unique_id:
description: An ID that uniquely identifies this fan. If two fans have the same unique ID, Home Assistant will raise an exception.
required: false
command_topic:
description: The MQTT topic to publish commands to change the fan state.
required: true
type: string
device:
description: "Information about the device this fan is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set."
required: false
type: map
keys:
identifiers:
description: A list of IDs that uniquely identify the device. For example a serial number.
required: false
type: [string, list]
connections:
description: 'A list of connections of the device to the outside world as a list of tuples `[connection_type, connection_identifier]`. For example the MAC address of a network interface: `"connections": [["mac", "02:5b:26:a8:dc:12"]]`.'
required: false
type: [list, map]
identifiers:
description: A list of IDs that uniquely identify the device. For example a serial number.
required: false
type: [string, list]
manufacturer:
description: The manufacturer of the device.
required: false
@ -178,6 +65,119 @@ device:
description: The firmware version of the device.
required: false
type: string
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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 fan.
required: false
type: string
default: MQTT Fan
optimistic:
description: Flag that defines if lock works in optimistic mode
required: false
type: boolean
default: "`true` if no state topic defined, else `false`."
oscillation_command_topic:
description: The MQTT topic to publish commands to change the oscillation state.
required: false
type: string
oscillation_state_topic:
description: The MQTT topic subscribed to receive oscillation state updates.
required: false
type: string
oscillation_value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the oscillation."
required: false
type: string
payload_available:
description: The payload that represents the available state.
required: false
type: string
default: online
payload_high_speed:
description: The payload that represents the fan's high speed.
required: false
type: string
default: high
payload_low_speed:
description: The payload that represents the fan's low speed.
required: false
type: string
default: low
payload_medium_speed:
description: The payload that represents the fan's medium speed.
required: false
type: string
default: medium
payload_not_available:
description: The payload that represents the unavailable state.
required: false
type: string
default: offline
payload_off:
description: The payload that represents the stop state.
required: false
type: string
default: "OFF"
payload_on:
description: The payload that represents the running state.
required: false
type: string
default: "ON"
payload_oscillation_off:
description: The payload that represents the oscillation off state.
required: false
type: string
default: oscillate_off
payload_oscillation_on:
description: The payload that represents the oscillation on state.
required: false
type: string
default: oscillate_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: true
speed_command_topic:
description: The MQTT topic to publish commands to change speed state.
required: false
type: string
speed_state_topic:
description: The MQTT topic subscribed to receive speed state updates.
required: false
type: string
speed_value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the speed payload."
required: false
type: string
speeds:
description: "List of speeds this fan is capable of running at. Valid entries are `off`, `low`, `medium` and `high`."
required: false
type: [string, list]
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 a value from the state."
required: false
type: string
unique_id:
description: An ID that uniquely identifies this fan. If two fans have the same unique ID, Home Assistant will raise an exception.
required: false
type: string
{% endconfiguration %}
<div class='note warning'>

440
source/_integrations/light.mqtt.markdown
View File

@ -45,19 +45,10 @@ light:
```
{% configuration %}
name:
description: The name of the light.
availability_topic:
description: The MQTT topic subscribed to receive availability (online/offline) updates.
required: false
type: string
default: MQTT Light
unique_id:
description: An ID that uniquely identifies this light. If two lights have the same unique ID, Home Assistant will raise an exception.
required: false
type: string
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
@ -91,10 +82,47 @@ color_temp_value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the color temperature value."
required: false
type: string
command_topic:
description: The MQTT topic to publish commands to change the switch state.
required: true
type: string
device:
description: 'Information about the device this light is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set.'
required: false
type: map
keys:
connections:
description: 'A list of connections of the device to the outside world as a list of tuples `[connection_type, connection_identifier]`. For example the MAC address of a network interface: `"connections": [["mac", "02:5b:26:a8:dc:12"]]`.'
required: false
type: list
identifiers:
description: 'A list of IDs that uniquely identify the device. For example a serial number.'
required: false
type: [string, list]
manufacturer:
description: 'The manufacturer of the device.'
required: false
type: string
model:
description: 'The model of the device.'
required: false
type: string
name:
description: 'The name of the device.'
required: false
type: string
sw_version:
description: 'The firmware version of the device.'
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_list:
description: The list of effects the light supports.
required: false
type: [string, list]
effect_state_topic:
description: The MQTT topic subscribed to receive effect state updates.
required: false
@ -103,10 +131,6 @@ 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]
hs_command_topic:
description: "The MQTT topic to publish commands to change the light's color state in HS format (Hue Saturation).
Range for Hue: 0° .. 360°, Range of Saturation: 0..100.
@ -122,6 +146,19 @@ hs_value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the HS value."
required: false
type: string
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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 light.
required: false
type: string
default: MQTT Light
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
@ -131,16 +168,26 @@ optimistic:
required: false
type: boolean
default: "`true` if no state topic defined, else `false`."
payload_on:
description: The payload that represents enabled state.
payload_available:
description: The payload that represents the available state.
required: false
type: string
default: "ON"
default: online
payload_not_available:
description: The payload that represents the unavailable state.
required: false
type: string
default: offline
payload_off:
description: The payload that represents disabled state.
required: false
type: string
default: "OFF"
payload_on:
description: The payload that represents enabled state.
required: false
type: string
default: "ON"
qos:
description: The maximum QoS level of the state topic.
required: false
@ -175,6 +222,10 @@ 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
unique_id:
description: An ID that uniquely identifies this light. If two lights have the same unique ID, Home Assistant will raise an exception.
required: false
type: string
white_value_command_topic:
description: "The MQTT topic to publish commands to change the light's white value."
required: false
@ -204,57 +255,6 @@ 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
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
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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
device:
description: 'Information about the device this light is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set.'
required: false
type: map
keys:
identifiers:
description: 'A list of IDs that uniquely identify the device. For example a serial number.'
required: false
type: [string, list]
connections:
description: 'A list of connections of the device to the outside world as a list of tuples `[connection_type, connection_identifier]`. For example the MAC address of a network interface: `"connections": [["mac", "02:5b:26:a8:dc:12"]]`.'
required: false
type: list
manufacturer:
description: 'The manufacturer of the device.'
required: false
type: string
model:
description: 'The model of the device.'
required: false
type: string
name:
description: 'The name of the device.'
required: false
type: string
sw_version:
description: 'The firmware version of the device.'
required: false
type: string
{% endconfiguration %}
<div class='note warning'>
@ -382,19 +382,10 @@ light:
```
{% configuration %}
name:
description: The name of the light.
availability_topic:
description: The MQTT topic subscribed to receive availability (online/offline) updates.
required: false
type: string
default: MQTT JSON Light
unique_id:
description: An ID that uniquely identifies this light. If two lights have the same unique ID, Home Assistant will raise an exception.
required: false
type: string
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
@ -410,6 +401,39 @@ color_temp:
required: false
type: boolean
default: false
command_topic:
description: The MQTT topic to publish commands to change the light’s state.
required: true
type: string
device:
description: 'Information about the device this light is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set.'
required: false
type: map
keys:
connections:
description: 'A list of connections of the device to the outside world as a list of tuples `[connection_type, connection_identifier]`. For example the MAC address of a network interface: `"connections": [["mac", "02:5b:26:a8:dc:12"]]`.'
required: false
type: list
identifiers:
description: 'A list of IDs that uniquely identify the device. For example a serial number.'
required: false
type: [string, list]
manufacturer:
description: 'The manufacturer of the device.'
required: false
type: string
model:
description: 'The model of the device.'
required: false
type: string
name:
description: 'The name of the device.'
required: false
type: string
sw_version:
description: 'The firmware version of the device.'
required: false
type: string
effect:
description: Flag that defines if the light supports effects.
required: false
@ -429,11 +453,39 @@ flash_time_short:
required: false
type: integer
default: 2
hs:
description: Flag that defines if the light supports HS colors.
required: false
type: boolean
default: false
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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 light.
required: false
type: string
default: MQTT JSON Light
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`."
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
qos:
description: The maximum QoS level of the state topic.
required: false
@ -453,6 +505,10 @@ state_topic:
description: The MQTT topic subscribed to receive state updates.
required: false
type: string
unique_id:
description: An ID that uniquely identifies this light. If two lights have the same unique ID, Home Assistant will raise an exception.
required: false
type: string
white_value:
description: Flag that defines if the light supports white values.
required: false
@ -463,62 +519,6 @@ xy:
required: false
type: boolean
default: false
hs:
description: Flag that defines if the light supports HS 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
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
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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
device:
description: 'Information about the device this light is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set.'
required: false
type: map
keys:
identifiers:
description: 'A list of IDs that uniquely identify the device. For example a serial number.'
required: false
type: [string, list]
connections:
description: 'A list of connections of the device to the outside world as a list of tuples `[connection_type, connection_identifier]`. For example the MAC address of a network interface: `"connections": [["mac", "02:5b:26:a8:dc:12"]]`.'
required: false
type: list
manufacturer:
description: 'The manufacturer of the device.'
required: false
type: string
model:
description: 'The model of the device.'
required: false
type: string
name:
description: 'The name of the device.'
required: false
type: string
sw_version:
description: 'The firmware version of the device.'
required: false
type: string
{% endconfiguration %}
<div class='note warning'>
@ -678,112 +678,47 @@ light:
```
{% configuration %}
name:
description: The name of the light.
required: false
type: string
default: MQTT Template Light
unique_id:
description: An ID that uniquely identifies this light. If two lights have the same unique ID, Home Assistant will raise an exception.
required: false
type: string
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`, `white_value`, `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."
availability_topic:
description: The MQTT topic subscribed to receive availability (online/offline) updates.
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
brightness_template:
description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract brightness 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
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
white_value_template:
description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract white value from the state payload value."
required: false
command_on_template:
description: "The [template](/docs/configuration/templating/#processing-incoming-data) for *on* state changes. Available variables: `state`, `brightness`, `red`, `green`, `blue`, `white_value`, `flash`, `transition` and `effect`."
required: true
type: string
optimistic:
description: Flag that defines if the light works in optimistic mode.
required: false
command_topic:
description: The MQTT topic to publish commands to change the light’s state.
required: true
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
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
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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
device:
description: 'Information about the device this light is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set.'
required: false
type: map
keys:
identifiers:
description: 'A list of IDs that uniquely identify the device. For example a serial number.'
required: false
type: [string, list]
connections:
description: 'A list of connections of the device to the outside world as a list of tuples `[connection_type, connection_identifier]`. For example the MAC address of a network interface: `"connections": [["mac", "02:5b:26:a8:dc:12"]]`.'
required: false
type: list
identifiers:
description: 'A list of IDs that uniquely identify the device. For example a serial number.'
required: false
type: [string, list]
manufacturer:
description: 'The manufacturer of the device.'
required: false
@ -800,6 +735,71 @@ device:
description: 'The firmware version of the device.'
required: false
type: string
effect_list:
description: List of possible effects.
required: false
type: [string, list]
effect_template:
description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract effect 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
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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 light.
required: false
type: string
default: MQTT Template Light
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`."
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
qos:
description: The maximum QoS level of the state topic.
required: false
type: integer
default: 0
red_template:
description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract red color from the state payload value."
required: false
type: string
state_template:
description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract state from the state payload value."
required: false
type: string
state_topic:
description: The MQTT topic subscribed to receive state updates.
required: false
type: string
unique_id:
description: An ID that uniquely identifies this light. If two lights have the same unique ID, Home Assistant will raise an exception.
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
{% endconfiguration %}
<div class='note warning'>

154
source/_integrations/lock.mqtt.markdown
View File

@ -28,97 +28,27 @@ lock:
```
{% configuration %}
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
name:
description: The name of the lock.
required: false
type: string
default: MQTT Lock
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
state_locked:
description: The value that represents the lock to be in locked state
required: false
type: string
default: LOCKED
state_unlocked:
description: The value that represents the lock to be in unlocked state
required: false
type: string
default: UNLOCKED
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
command_topic:
description: The MQTT topic to publish commands to change the lock state.
required: true
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](/integrations/sensor.mqtt/#json-attributes-topic-configuration) documentation.
required: false
type: string
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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
unique_id:
description: An ID that uniquely identifies this lock. If two locks have the same unique ID, Home Assistant will raise an exception.
required: false
type: string
device:
description: 'Information about the device this lock is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set.'
required: false
type: map
keys:
identifiers:
description: 'A list of IDs that uniquely identify the device. For example a serial number.'
required: false
type: [string, list]
connections:
description: 'A list of connections of the device to the outside world as a list of tuples `[connection_type, connection_identifier]`. For example the MAC address of a network interface: `"connections": [["mac", "02:5b:26:a8:dc:12"]]`.'
required: false
type: list
identifiers:
description: 'A list of IDs that uniquely identify the device. For example a serial number.'
required: false
type: [string, list]
manufacturer:
description: 'The manufacturer of the device.'
required: false
@ -135,6 +65,76 @@ device:
description: 'The firmware version of the device.'
required: false
type: string
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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 lock.
required: false
type: string
default: MQTT Lock
optimistic:
description: Flag that defines if lock works in optimistic mode.
required: false
type: string
default: "`true` if no `state_topic` defined, else `false`."
payload_available:
description: The payload that represents the available state.
required: false
type: string
default: online
payload_lock:
description: The payload that represents enabled/locked state.
required: false
type: string
default: LOCK
payload_not_available:
description: The payload that represents the unavailable state.
required: false
type: string
default: offline
payload_unlock:
description: The payload that represents disabled/unlocked state.
required: false
type: string
default: UNLOCK
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
state_locked:
description: The value that represents the lock to be in locked state
required: false
type: string
default: LOCKED
state_topic:
description: The MQTT topic subscribed to receive state updates.
required: false
type: string
state_unlocked:
description: The value that represents the lock to be in unlocked state
required: false
type: string
default: UNLOCKED
unique_id:
description: An ID that uniquely identifies this lock. If two locks have the same unique ID, Home Assistant will raise an exception.
required: false
type: string
value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload."
required: false
type: string
{% endconfiguration %}
<div class='note warning'>

142
source/_integrations/sensor.mqtt.markdown
View File

@ -22,90 +22,23 @@ sensor:
```
{% configuration %}
state_topic:
description: The MQTT topic subscribed to receive sensor values.
required: true
type: string
name:
description: The name of the MQTT sensor.
required: false
type: string
default: MQTT Sensor
qos:
description: The maximum QoS level of the state topic.
required: false
type: integer
default: 0
unit_of_measurement:
description: Defines the units of measurement of the sensor, if any.
required: false
type: string
icon:
description: The icon for the sensor.
required: false
type: icon
expire_after:
description: Defines the number of seconds after the value expires if it's not updated.
required: false
type: integer
default: 0
value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the value."
required: false
type: template
force_update:
description: Sends update events even if the value hasn't changed. Useful if you want to have meaningful value graphs in history.
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
json_attributes_topic:
description: The MQTT topic subscribed to receive a JSON dictionary payload and then set as sensor attributes. Implies `force_update` of the current sensor state when a message is received on this topic.
required: false
type: string
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the JSON dictionary from messages received on the `json_attributes_topic`."
required: false
type: template
json_attributes:
description: (Deprecated, replaced by json_attributes_topic) A list of keys to extract values from a JSON dictionary payload and then set as sensor attributes.
required: false
type: [string, list]
unique_id:
description: "An ID that uniquely identifies this sensor. If two sensors have the same unique ID, Home Assistant will raise an exception."
required: false
type: string
device_class:
description: The [type/class](/integrations/sensor/#device-class) of the sensor to set the icon in the frontend.
required: false
type: device_class
default: None
device:
description: "Information about the device this sensor is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set."
required: false
type: map
keys:
identifiers:
description: A list of IDs that uniquely identify the device. For example a serial number.
required: false
type: [string, list]
connections:
description: 'A list of connections of the device to the outside world as a list of tuples `[connection_type, connection_identifier]`. For example the MAC address of a network interface: `"connections": [["mac", "02:5b:26:a8:dc:12"]]`.'
required: false
type: list
identifiers:
description: A list of IDs that uniquely identify the device. For example a serial number.
required: false
type: [string, list]
manufacturer:
description: The manufacturer of the device.
required: false
@ -122,6 +55,73 @@ device:
description: The firmware version of the device.
required: false
type: string
device_class:
description: The [type/class](/integrations/sensor/#device-class) of the sensor to set the icon in the frontend.
required: false
type: device_class
default: None
expire_after:
description: Defines the number of seconds after the value expires if it's not updated.
required: false
type: integer
default: 0
force_update:
description: Sends update events even if the value hasn't changed. Useful if you want to have meaningful value graphs in history.
reqired: false
type: boolean
default: false
icon:
description: The icon for the sensor.
required: false
type: icon
json_attributes:
description: (Deprecated, replaced by json_attributes_topic) A list of keys to extract values from a JSON dictionary payload and then set as sensor attributes.
required: false
type: [string, list]
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the JSON dictionary from messages received on the `json_attributes_topic`."
required: false
type: template
json_attributes_topic:
description: The MQTT topic subscribed to receive a JSON dictionary payload and then set as sensor attributes. Implies `force_update` of the current sensor state when a message is received on this topic.
required: false
type: string
name:
description: The name of the MQTT sensor.
required: false
type: string
default: MQTT Sensor
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
qos:
description: The maximum QoS level of the state topic.
required: false
type: integer
default: 0
state_topic:
description: The MQTT topic subscribed to receive sensor values.
required: true
type: string
unique_id:
description: "An ID that uniquely identifies this sensor. If two sensors have the same unique ID, Home Assistant will raise an exception."
required: false
type: string
unit_of_measurement:
description: Defines the units of measurement of the sensor, if any.
required: false
type: string
value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the value."
required: false
type: template
{% endconfiguration %}
## Examples

152
source/_integrations/switch.mqtt.markdown
View File

@ -28,97 +28,27 @@ switch:
```
{% configuration %}
command_topic:
description: The MQTT topic to publish commands to change the switch state.
required: false
type: string
name:
description: The name to use when displaying this switch.
required: false
type: string
default: MQTT Switch
icon:
description: Icon for the switch.
required: false
type: icon
state_topic:
description: The MQTT topic subscribed to receive state updates.
required: false
type: string
state_on:
description: The payload that represents the on state.
required: false
type: string
default: "`payload_on` if defined, else ON"
state_off:
description: The payload that represents the off state.
required: false
type: string
default: "`payload_off` if defined, else OFF"
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.
command_topic:
description: The MQTT topic to publish commands to change the switch 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
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
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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
device:
description: "Information about the device this switch is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set."
required: false
type: map
keys:
identifiers:
description: A list of IDs that uniquely identify the device. For example a serial number.
required: false
type: [string, list]
connections:
description: 'A list of connections of the device to the outside world as a list of tuples `[connection_type, connection_identifier]`. For example the MAC address of a network interface: `"connections": [["mac", "02:5b:26:a8:dc:12"]]`.'
required: false
type: list
identifiers:
description: A list of IDs that uniquely identify the device. For example a serial number.
required: false
type: [string, list]
manufacturer:
description: The manufacturer of the device.
required: false
@ -135,6 +65,76 @@ device:
description: The firmware version of the device.
required: false
type: string
icon:
description: Icon for the switch.
required: false
type: icon
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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 to use when displaying this switch.
required: false
type: string
default: MQTT Switch
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_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
payload_off:
description: The payload that represents disabled state.
required: false
type: string
default: "OFF"
payload_on:
description: The payload that represents enabled state.
required: false
type: string
default: "ON"
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
state_off:
description: The payload that represents the off state.
required: false
type: string
default: "`payload_off` if defined, else OFF"
state_on:
description: The payload that represents the on state.
required: false
type: string
default: "`payload_on` if defined, else ON"
state_topic:
description: The MQTT topic subscribed to receive state updates.
required: false
type: string
value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload."
required: false
type: string
{% endconfiguration %}
<div class='note warning'>

342
source/_integrations/vacuum.mqtt.markdown
View File

@ -29,55 +29,84 @@ vacuum:
Legacy MQTT vacuum configuration section.
{% configuration %}
availability_topic:
description: The MQTT topic subscribed to receive availability (online/offline) updates.
required: false
type: string
battery_level_template:
description: Defines a [template](/topics/templating/) to define the battery level of the vacuum. This is required if `battery_level_topic` is set.
required: false
type: string
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](/topics/templating/) to define the charging state of the vacuum. This is required if `charging_topic` is set.
required: false
type: string
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](/topics/templating/) to define the cleaning state of the vacuum. This is required if `cleaning_topic` is set.
required: false
type: string
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](/topics/templating/) to define the docked state of the vacuum. This is required if `docked_topic` is set.
required: false
type: string
docked_topic:
description: The MQTT topic subscribed to receive docked state values from the vacuum.
required: false
type: string
error_template:
description: Defines a [template](/topics/templating/) to define potential error messages emitted by the vacuum. This is required if `error_topic` is set.
required: false
type: string
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](/topics/templating/) to define the fan speed of the vacuum. This is required if `fan_speed_topic` is set.
required: false
type: string
fan_speed_topic:
description: The MQTT topic subscribed to receive fan speed values from the vacuum.
required: false
type: string
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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
schema:
description: The schema to use.
payload_available:
description: The payload that represents the available state.
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`)."
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
default: online
payload_clean_spot:
description: The payload to send to the `command_topic` to begin a spot cleaning cycle.
required: false
@ -88,93 +117,64 @@ payload_locate:
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
battery_level_topic:
description: The MQTT topic subscribed to receive battery level values from the vacuum.
payload_stop:
description: The payload to send to the `command_topic` to stop the vacuum.
required: false
type: string
battery_level_template:
description: Defines a [template](/topics/templating/) to define the battery level of the vacuum. This is required if `battery_level_topic` is set.
default: stop
payload_turn_off:
description: The payload to send to the `command_topic` to turn the vacuum off.
required: false
type: string
charging_topic:
description: The MQTT topic subscribed to receive charging state values from the vacuum.
default: turn_off
payload_turn_on:
description: The payload to send to the `command_topic` to begin the cleaning cycle.
required: false
type: string
charging_template:
description: Defines a [template](/topics/templating/) to define the charging state of the vacuum. This is required if `charging_topic` is set.
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.
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. This is required if `cleaning_topic` is set.
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. This is required if `docked_topic` is set.
required: false
type: string
error_topic:
description: The MQTT topic subscribed to receive error messages from the vacuum.
required: false
type: string
error_template:
description: Defines a [template](/topics/templating/) to define potential error messages emitted by the vacuum. This is required if `error_topic` is set.
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. This is required if `fan_speed_topic` is set.
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
fan_speed_list:
description: List of possible fan speeds for the 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]
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](/integrations/sensor.mqtt/#json-attributes-topic-configuration) documentation.
required: false
type: string
json_attributes_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) 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
default: "`turn_on`, `turn_off`, `stop`, `return_home`, `status`, `battery`, `clean_spot`"
{% endconfiguration %}
### Legacy configuration example
@ -260,50 +260,32 @@ MQTT payload:
State MQTT vacuum configuration section.
{% configuration %}
availability_topic:
description: The MQTT topic subscribed to receive availability (online/offline) updates.
required: false
type: string
command_topic:
description: The MQTT topic to publish commands to control the vacuum.
required: false
type: string
fan_speed_list:
description: List of possible fan speeds for the vacuum.
required: false
type: [string, list]
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
schema:
description: The schema to use.
payload_available:
description: The payload that represents the available state.
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
default: online
payload_clean_spot:
description: The payload to send to the `command_topic` to begin a spot cleaning cycle.
required: false
@ -314,47 +296,65 @@ payload_locate:
required: false
type: string
default: locate
payload_not_available:
description: The payload that represents the unavailable state.
required: false
type: string
default: offline
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.
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
value_template:
description: "Defines a [template](/topics/templating/) to extract possible states from the vacuum."
default: return_to_base
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
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.
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
fan_speed_list:
description: List of possible fan speeds for the vacuum.
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
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]
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](/integrations/sensor.mqtt/#json-attributes-topic-configuration) documentation.
default: "`start`, `stop`, `return_home`, `status`, `battery`, `clean_spot`"
value_template:
description: "Defines a [template](/topics/templating/) to extract possible states from the vacuum."
required: false
type: string
{% endconfiguration %}