mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-21 08:16:53 +00:00
Document MQTT availability list (#13929)
Co-authored-by: Klaas Schoute <klaas_schoute@hotmail.com> Co-authored-by: Franck Nijhof <git@frenck.dev>
This commit is contained in:
Erik Montnemery
GitHub
parent
b5b555bd67
commit
dfd18e447e
@ -37,8 +37,27 @@ alarm_control_panel:
|
||||
```
|
||||
|
||||
{% configuration %}
|
||||
availability:
|
||||
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
|
||||
required: false
|
||||
type: list
|
||||
keys:
|
||||
payload_available:
|
||||
description: The payload that represents the available state.
|
||||
required: false
|
||||
type: string
|
||||
default: online
|
||||
payload_not_available:
|
||||
description: The payload that represents the unavailable state.
|
||||
required: false
|
||||
type: string
|
||||
default: offline
|
||||
topic:
|
||||
description: An MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
required: true
|
||||
type: string
|
||||
availability_topic:
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`.
|
||||
required: false
|
||||
type: string
|
||||
code:
|
||||
|
||||
@ -18,8 +18,7 @@ Stateless devices such as buttons, remote controls etc are better represented by
|
||||
|
||||
## Configuration
|
||||
|
||||
The `mqtt` binary sensor platform optionally supports an `availability_topic` to receive online and offline messages (birth and LWT messages) from the MQTT device. During normal operation, if the MQTT sensor device goes offline (i.e., publishes `payload_not_available` to `availability_topic`), Home Assistant will display the binary sensor as `unavailable`. If these messages are published with the `retain` flag set, the binary sensor will receive an instant update after subscription and Home Assistant will display the correct availability state of the binary sensor when Home Assistant starts up. If the `retain` flag is not set, Home Assistant will display the binary sensor as `unavailable` when Home Assistant starts up. If no `availability_topic`
|
||||
is defined, Home Assistant will consider the MQTT device to be `available` and will display its state.
|
||||
The `mqtt` binary sensor platform optionally supports a list of `availability` topics to receive online and offline messages (birth and LWT messages) from the MQTT device. During normal operation, if the MQTT sensor device goes offline (i.e., publishes `payload_not_available` to an `availability` topic), Home Assistant will display the binary sensor as `unavailable`. If these messages are published with the `retain` flag set, the binary sensor will receive an instant update after subscription and Home Assistant will display the correct availability state of the binary sensor when Home Assistant starts up. If the `retain` flag is not set, Home Assistant will display the binary sensor as `unavailable` when Home Assistant starts up. If no `availability` topic is defined, Home Assistant will consider the MQTT device to be `available` and will display its state.
|
||||
|
||||
To use an MQTT binary sensor in your installation,
|
||||
add the following to your `configuration.yaml` file:
|
||||
@ -32,8 +31,27 @@ binary_sensor:
|
||||
```
|
||||
|
||||
{% configuration %}
|
||||
availability:
|
||||
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
|
||||
required: false
|
||||
type: list
|
||||
keys:
|
||||
payload_available:
|
||||
description: The payload that represents the available state.
|
||||
required: false
|
||||
type: string
|
||||
default: online
|
||||
payload_not_available:
|
||||
description: The payload that represents the unavailable state.
|
||||
required: false
|
||||
type: string
|
||||
default: offline
|
||||
topic:
|
||||
description: An MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
required: true
|
||||
type: string
|
||||
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 will always be considered `available` and its state will be `on`, `off` or `unknown`. If `availability_topic` is defined, the binary sensor will be considered as `unavailable` by default and the sensor's state will be `unavailable`."
|
||||
description: "The MQTT topic subscribed to receive birth and LWT messages from the MQTT device. If `availability` is not defined, the binary sensor will always be considered `available` and its state will be `on`, `off` or `unknown`. If `availability` is defined, the binary sensor will be considered as `unavailable` by default and the sensor's initial state will be `unavailable`. Must not be used together with `availability`."
|
||||
required: false
|
||||
type: string
|
||||
device:
|
||||
@ -74,7 +92,7 @@ device_class:
|
||||
required: false
|
||||
type: string
|
||||
expire_after:
|
||||
description: "Defines the number of seconds after the sensor's state expires if it's not updated. After expiry, the sensor's state becomes `unavailable` if `availability_topic` is defined and `unknown` otherwise."
|
||||
description: "Defines the number of seconds after the sensor's state expires if it's not updated. After expiry, the sensor's state becomes `unavailable` if any `availability` topic is defined and `unknown` otherwise."
|
||||
required: false
|
||||
type: integer
|
||||
force_update:
|
||||
@ -164,7 +182,8 @@ binary_sensor:
|
||||
state_topic: "home-assistant/window/contact"
|
||||
payload_on: "ON"
|
||||
payload_off: "OFF"
|
||||
availability_topic: "home-assistant/window/availability"
|
||||
availability:
|
||||
- topic: "home-assistant/window/availability"
|
||||
payload_available: "online"
|
||||
payload_not_available: "offline"
|
||||
qos: 0
|
||||
|
||||
@ -24,8 +24,27 @@ camera:
|
||||
```
|
||||
|
||||
{% configuration %}
|
||||
availability:
|
||||
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
|
||||
required: false
|
||||
type: list
|
||||
keys:
|
||||
payload_available:
|
||||
description: The payload that represents the available state.
|
||||
required: false
|
||||
type: string
|
||||
default: online
|
||||
payload_not_available:
|
||||
description: The payload that represents the unavailable state.
|
||||
required: false
|
||||
type: string
|
||||
default: offline
|
||||
topic:
|
||||
description: An MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
required: true
|
||||
type: string
|
||||
availability_topic:
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`.
|
||||
required: false
|
||||
type: string
|
||||
device:
|
||||
|
||||
@ -43,8 +43,27 @@ 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
|
||||
availability:
|
||||
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
|
||||
required: false
|
||||
type: list
|
||||
keys:
|
||||
payload_available:
|
||||
description: The payload that represents the available state.
|
||||
required: false
|
||||
type: string
|
||||
default: online
|
||||
payload_not_available:
|
||||
description: The payload that represents the unavailable state.
|
||||
required: false
|
||||
type: string
|
||||
default: offline
|
||||
topic:
|
||||
description: An MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
required: true
|
||||
type: string
|
||||
availability_topic:
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`.
|
||||
required: false
|
||||
type: string
|
||||
away_mode_command_topic:
|
||||
|
||||
@ -25,7 +25,7 @@ If a state topic and position topic are not defined, the cover will work in opti
|
||||
|
||||
Optimistic mode can be forced, even if a `state_topic` / `position_topic` is defined. Try to enable it if experiencing incorrect cover operation (Google Assistant gauge may need optimistic mode as it often send request to your Home Assistant immediately after send set_cover_position in which case MQTT could be too slow).
|
||||
|
||||
The `mqtt` cover platform optionally supports an `availability_topic` to receive online and offline messages (birth and LWT messages) from the MQTT cover device. During normal operation, if the MQTT cover device goes offline (i.e., publishes `payload_not_available` to `availability_topic`), Home Assistant will display the cover as "unavailable". If these messages are published with the `retain` flag set, the cover will receive an instant update after subscription and Home Assistant will display correct availability state of the cover when Home Assistant starts up. If the `retain` flag is not set, Home Assistant will display the cover as "unavailable" when Home Assistant starts up.
|
||||
The `mqtt` cover platform optionally supports a list of `availability` topics to receive online and offline messages (birth and LWT messages) from the MQTT cover device. During normal operation, if the MQTT cover device goes offline (i.e., publishes a matching `payload_not_available` to any `availability` topic), Home Assistant will display the cover as "unavailable". If these messages are published with the `retain` flag set, the cover will receive an instant update after subscription and Home Assistant will display correct availability state of the cover when Home Assistant starts up. If the `retain` flag is not set, Home Assistant will display the cover as "unavailable" when Home Assistant starts up.
|
||||
|
||||
To use your MQTT cover in your installation, add the following to your `configuration.yaml` file:
|
||||
|
||||
@ -37,8 +37,27 @@ cover:
|
||||
```
|
||||
|
||||
{% configuration %}
|
||||
availability:
|
||||
description: "A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`."
|
||||
required: false
|
||||
type: map
|
||||
keys:
|
||||
payload_available:
|
||||
description: The payload that represents the available state.
|
||||
required: false
|
||||
type: string
|
||||
default: online
|
||||
payload_not_available:
|
||||
description: The payload that represents the unavailable state.
|
||||
required: false
|
||||
type: string
|
||||
default: offline
|
||||
topic:
|
||||
description: An MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
required: true
|
||||
type: string
|
||||
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."
|
||||
description: "The MQTT topic subscribed to to receive birth and LWT messages from the MQTT cover device. If an `availability` topic is not defined, the cover availability state will always be `available`. If an `availability` topic is defined, the cover availability state will be `unavailable` by default. Must not be used together with `availability`."
|
||||
required: false
|
||||
type: string
|
||||
command_topic:
|
||||
@ -250,7 +269,8 @@ cover:
|
||||
name: "MQTT Cover"
|
||||
command_topic: "home-assistant/cover/set"
|
||||
state_topic: "home-assistant/cover/state"
|
||||
availability_topic: "home-assistant/cover/availability"
|
||||
availability:
|
||||
- topic: "home-assistant/cover/availability"
|
||||
qos: 0
|
||||
retain: true
|
||||
payload_open: "OPEN"
|
||||
@ -281,7 +301,8 @@ cover:
|
||||
name: "MQTT Cover"
|
||||
command_topic: "home-assistant/cover/set"
|
||||
position_topic: "home-assistant/cover/position"
|
||||
availability_topic: "home-assistant/cover/availability"
|
||||
availability:
|
||||
- "home-assistant/cover/availability"
|
||||
set_position_topic: "home-assistant/cover/set_position"
|
||||
qos: 0
|
||||
retain: true
|
||||
@ -311,7 +332,8 @@ cover:
|
||||
name: "MQTT Cover"
|
||||
command_topic: "home-assistant/cover/set"
|
||||
state_topic: "home-assistant/cover/state"
|
||||
availability_topic: "home-assistant/cover/availability"
|
||||
availability:
|
||||
- topic: "home-assistant/cover/availability"
|
||||
qos: 0
|
||||
retain: true
|
||||
payload_open: "OPEN"
|
||||
|
||||
@ -28,8 +28,27 @@ fan:
|
||||
```
|
||||
|
||||
{% configuration %}
|
||||
availability:
|
||||
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
|
||||
required: false
|
||||
type: list
|
||||
keys:
|
||||
payload_available:
|
||||
description: The payload that represents the available state.
|
||||
required: false
|
||||
type: string
|
||||
default: online
|
||||
payload_not_available:
|
||||
description: The payload that represents the unavailable state.
|
||||
required: false
|
||||
type: string
|
||||
default: offline
|
||||
topic:
|
||||
description: An MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
required: true
|
||||
type: string
|
||||
availability_topic:
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`.
|
||||
required: false
|
||||
type: string
|
||||
command_topic:
|
||||
|
||||
@ -45,8 +45,27 @@ light:
|
||||
```
|
||||
|
||||
{% configuration %}
|
||||
availability:
|
||||
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
|
||||
required: false
|
||||
type: list
|
||||
keys:
|
||||
payload_available:
|
||||
description: The payload that represents the available state.
|
||||
required: false
|
||||
type: string
|
||||
default: online
|
||||
payload_not_available:
|
||||
description: The payload that represents the unavailable state.
|
||||
required: false
|
||||
type: string
|
||||
default: offline
|
||||
topic:
|
||||
description: An MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
required: true
|
||||
type: string
|
||||
availability_topic:
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`.
|
||||
required: false
|
||||
type: string
|
||||
brightness_command_topic:
|
||||
@ -399,8 +418,27 @@ light:
|
||||
```
|
||||
|
||||
{% configuration %}
|
||||
availability:
|
||||
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
|
||||
required: false
|
||||
type: list
|
||||
keys:
|
||||
payload_available:
|
||||
description: The payload that represents the available state.
|
||||
required: false
|
||||
type: string
|
||||
default: online
|
||||
payload_not_available:
|
||||
description: The payload that represents the unavailable state.
|
||||
required: false
|
||||
type: string
|
||||
default: offline
|
||||
topic:
|
||||
description: An MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
required: true
|
||||
type: string
|
||||
availability_topic:
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`.
|
||||
required: false
|
||||
type: string
|
||||
brightness:
|
||||
@ -708,8 +746,27 @@ light:
|
||||
```
|
||||
|
||||
{% configuration %}
|
||||
availability:
|
||||
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
|
||||
required: false
|
||||
type: list
|
||||
keys:
|
||||
payload_available:
|
||||
description: The payload that represents the available state.
|
||||
required: false
|
||||
type: string
|
||||
default: online
|
||||
payload_not_available:
|
||||
description: The payload that represents the unavailable state.
|
||||
required: false
|
||||
type: string
|
||||
default: offline
|
||||
topic:
|
||||
description: An MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
required: true
|
||||
type: string
|
||||
availability_topic:
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`.
|
||||
required: false
|
||||
type: string
|
||||
blue_template:
|
||||
|
||||
@ -28,8 +28,27 @@ lock:
|
||||
```
|
||||
|
||||
{% configuration %}
|
||||
availability:
|
||||
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
|
||||
required: false
|
||||
type: list
|
||||
keys:
|
||||
payload_available:
|
||||
description: The payload that represents the available state.
|
||||
required: false
|
||||
type: string
|
||||
default: online
|
||||
payload_not_available:
|
||||
description: The payload that represents the unavailable state.
|
||||
required: false
|
||||
type: string
|
||||
default: offline
|
||||
topic:
|
||||
description: An MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
required: true
|
||||
type: string
|
||||
availability_topic:
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`.
|
||||
required: false
|
||||
type: string
|
||||
command_topic:
|
||||
|
||||
@ -143,7 +143,8 @@ sensor:
|
||||
state_topic: "home/sensor1/infojson"
|
||||
unit_of_measurement: 'dBm'
|
||||
value_template: "{{ value_json.RSSI }}"
|
||||
availability_topic: "home/sensor1/status"
|
||||
availability:
|
||||
- topic: "home/sensor1/status"
|
||||
payload_available: "online"
|
||||
payload_not_available: "offline"
|
||||
json_attributes_topic: "home/sensor1/attributes"
|
||||
|
||||
@ -28,8 +28,27 @@ switch:
|
||||
```
|
||||
|
||||
{% configuration %}
|
||||
availability:
|
||||
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
|
||||
required: false
|
||||
type: list
|
||||
keys:
|
||||
payload_available:
|
||||
description: The payload that represents the available state.
|
||||
required: false
|
||||
type: string
|
||||
default: online
|
||||
payload_not_available:
|
||||
description: The payload that represents the unavailable state.
|
||||
required: false
|
||||
type: string
|
||||
default: offline
|
||||
topic:
|
||||
description: An MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
required: true
|
||||
type: string
|
||||
availability_topic:
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`.
|
||||
required: false
|
||||
type: string
|
||||
command_topic:
|
||||
@ -167,7 +186,8 @@ switch:
|
||||
name: "Bedroom Switch"
|
||||
state_topic: "home/bedroom/switch1"
|
||||
command_topic: "home/bedroom/switch1/set"
|
||||
availability_topic: "home/bedroom/switch1/available"
|
||||
availability:
|
||||
- topic: "home/bedroom/switch1/available"
|
||||
payload_on: "ON"
|
||||
payload_off: "OFF"
|
||||
state_on: "ON"
|
||||
|
||||
@ -29,8 +29,27 @@ vacuum:
|
||||
Legacy MQTT vacuum configuration section.
|
||||
|
||||
{% configuration %}
|
||||
availability:
|
||||
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
|
||||
required: false
|
||||
type: list
|
||||
keys:
|
||||
payload_available:
|
||||
description: The payload that represents the available state.
|
||||
required: false
|
||||
type: string
|
||||
default: online
|
||||
payload_not_available:
|
||||
description: The payload that represents the unavailable state.
|
||||
required: false
|
||||
type: string
|
||||
default: offline
|
||||
topic:
|
||||
description: An MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
required: true
|
||||
type: string
|
||||
availability_topic:
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`.
|
||||
required: false
|
||||
type: string
|
||||
battery_level_template:
|
||||
@ -265,8 +284,27 @@ MQTT payload:
|
||||
State MQTT vacuum configuration section.
|
||||
|
||||
{% configuration %}
|
||||
availability:
|
||||
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
|
||||
required: false
|
||||
type: list
|
||||
keys:
|
||||
payload_available:
|
||||
description: The payload that represents the available state.
|
||||
required: false
|
||||
type: string
|
||||
default: online
|
||||
payload_not_available:
|
||||
description: The payload that represents the unavailable state.
|
||||
required: false
|
||||
type: string
|
||||
default: offline
|
||||
topic:
|
||||
description: An MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
required: true
|
||||
type: string
|
||||
availability_topic:
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates.
|
||||
description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`.
|
||||
required: false
|
||||
type: string
|
||||
command_topic:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user