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-15 13:26:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Consequent documentation of MQTT entity set up (#39951)

Browse Source
This commit is contained in:
Jan Bouwhuis 2025-07-10 06:41:58 +02:00 committed by GitHub
parent f7e08e96c6
commit 14cefb3868
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
26 changed files with 137 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -30,7 +30,7 @@ The {% term integration %} can control your Alarm Panel by publishing to the `co
## Configuration
To enable this {% term integration %}, add the following lines to your {% term "`configuration.yaml`" %} file.
To use an MQTT alarm control panel in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
@ -41,6 +41,8 @@ mqtt:
command_topic: "home/alarm/set"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.

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

@ -20,16 +20,18 @@ Stateless devices such as buttons, remote controls etc are better represented by
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 {% term "`configuration.yaml`" %} file:
To use an MQTT binary sensor in your installation, [add a MQTT device as a subentry](/integrations/mqtt/#configuration), or add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
mqtt:
- binary_sensor:
state_topic: "home-assistant/window/contact"
state_topic: "basement/window/contact"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
@ -245,10 +247,10 @@ The example below shows a full configuration for a binary sensor:
mqtt:
- binary_sensor:
name: "Window Contact Sensor"
state_topic: "home-assistant/window/contact"
state_topic: "bedroom/window/contact"
payload_on: "ON"
availability:
- topic: "home-assistant/window/availability"
- topic: "bedroom/window/availability"
payload_available: "online"
payload_not_available: "offline"
qos: 0

5
source/_integrations/button.mqtt.markdown
View File

@ -10,6 +10,9 @@ ha_domain: mqtt
The `mqtt` button platform lets you send an MQTT message when the button is pressed in the frontend or the button press action is called. This can be used to expose some service of a remote device, for example reboot.
To use an MQTT button in your installation, [add a MQTT device as a subentry](/integrations/mqtt/#configuration), or add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
## Configuration
```yaml
@ -19,6 +22,8 @@ mqtt:
command_topic: "home/bedroom/switch1/reboot"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.

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

@ -14,7 +14,8 @@ This can be used with an application or a service capable of sending images thro
## Configuration
To enable this camera in your installation, add the following to your {% term "`configuration.yaml`" %} file:
To use an MQTT camera in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
@ -23,6 +24,8 @@ mqtt:
topic: zanzito/shared_locations/my-device
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
The sample configuration above can be tested by publishing an image to the topic from the console:
```shell

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

@ -12,7 +12,7 @@ The `mqtt` climate platform lets you control your MQTT enabled HVAC devices.
## Configuration
To enable this climate platform in your installation, first add the following to your {% term "`configuration.yaml`" %} file.
To use an MQTT climate in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
@ -23,6 +23,8 @@ mqtt:
mode_command_topic: "study/ac/mode/set"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
action_template:
description: A template to render the value received on the `action_topic` with.

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

@ -27,7 +27,8 @@ Optimistic mode can be forced, even if a `state_topic` / `position_topic` is def
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 {% term "`configuration.yaml`" %} file:
To use an MQTT cover in your installation, [add a MQTT device as a subentry](/integrations/mqtt/#configuration), or add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
@ -36,6 +37,8 @@ mqtt:
command_topic: "living-room-cover/set"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: "A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`."

5
source/_integrations/device_tracker.mqtt.markdown
View File

@ -16,7 +16,8 @@ The `mqtt` device tracker {% term integration %} allows you to define new device
## Configuration
To use this device tracker in your installation, add the following to your {% term "`configuration.yaml`" %} file:
To use an MQTT device tracker in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
@ -29,6 +30,8 @@ mqtt:
state_topic: "location/paulus"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.

5
source/_integrations/event.mqtt.markdown
View File

@ -12,6 +12,9 @@ The `mqtt` event platform allows you to process event info from an MQTT message.
## Configuration
To use an MQTT event entity in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
mqtt:
@ -21,6 +24,8 @@ mqtt:
- press
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.

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

@ -18,7 +18,7 @@ When a `state_topic` is not available, the fan will work in optimistic mode. In
Optimistic mode can be forced even if a `state_topic` is available. Try to enable it if you are experiencing incorrect fan operation.
To enable MQTT fans in your installation, add the following to your {% term "`configuration.yaml`" %} file.
To use an MQTT fan in your installation, [add a MQTT device as a subentry](/integrations/mqtt/#configuration), or add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
@ -28,6 +28,8 @@ mqtt:
command_topic: "bedroom_fan/on/set"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.

5
source/_integrations/humidifier.mqtt.markdown
View File

@ -18,7 +18,8 @@ When a `state_topic` is not available, the humidifier will work in optimistic mo
Optimistic mode can be forced even if a `state_topic` is available. Try to enable it if you are experiencing incorrect humidifier operation.
To enable MQTT humidifiers in your installation, add the following to your {% term "`configuration.yaml`" %} file:
To use an MQTT humidifier in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
@ -28,6 +29,8 @@ mqtt:
target_humidity_command_topic: "bedroom_humidifier/humidity/set"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
action_template:
description: A template to render the value received on the `action_topic` with.

5
source/_integrations/image.mqtt.markdown
View File

@ -18,7 +18,8 @@ An alternative setup is to use the `url_topic` option to receive an image URL fo
## Configuration
To enable this image in your installation, add the following to your {% term "`configuration.yaml`" %} file:
To use an MQTT image entity in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
@ -27,6 +28,8 @@ mqtt:
url_topic: mynas/status/url
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.

5
source/_integrations/lawn_mower.mqtt.markdown
View File

@ -12,7 +12,8 @@ The `mqtt` `lawn_mower` platform allows controlling a lawn mower over MQTT.
## Configuration
To enable MQTT lawn mower in your installation, add the following to your {% term "`configuration.yaml`" %} file:
To use an MQTT lawn mower in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
@ -22,6 +23,8 @@ mqtt:
name: "Test Lawn Mower"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
activity_state_topic:
description: The MQTT topic subscribed to receive an update of the activity. Valid activities are `mowing`, `paused`, `docked`, and `error`. Use `value_template` to extract the activity state from a custom payload. When payload `none` is received, the activity state will be reset to `unknown`.

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

@ -42,6 +42,9 @@ Optimistic mode can be forced, even if the `state_topic` is available. Try to en
Home Assistant internally assumes that a light's state corresponds to a defined `color_mode`.
The state of MQTT lights with default schema and support for both color and color temperature will set the `color_mode` according to the last received valid color or color temperature. Optionally, a `color_mode_state_topic` can be configured for explicit control of the `color_mode`.
To use an MQTT basic light in your installation, [add a MQTT device as a subentry](/integrations/mqtt/#configuration), or add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
mqtt:
@ -49,6 +52,8 @@ mqtt:
command_topic: "office/rgb1/light/switch"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
@ -542,6 +547,9 @@ When a state topic is not available, the light will work in optimistic mode. In
Optimistic mode can be forced, even if state topic is available. Try enabling it if the light is operating incorrectly.
To use an MQTT JSON light in your installation, [add a MQTT device as a subentry](/integrations/mqtt/#configuration), or add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
mqtt:
@ -550,6 +558,8 @@ mqtt:
command_topic: "home/rgb1/set"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
@ -948,6 +958,9 @@ When a state topic is not available, the light will work in optimistic mode. In
Optimistic mode can be forced, even if state topic is available. Try enabling it if the light is operating incorrectly.
To use an MQTT template light in your installation, [add a MQTT device as a subentry](/integrations/mqtt/#configuration), or add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
mqtt:
@ -958,6 +971,8 @@ mqtt:
command_off_template: "off"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.

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

@ -21,7 +21,9 @@ Optimistic mode can be forced, even if state topic is available. Try to enable i
It's mandatory for locks to support `lock` and `unlock`. A lock may optionally support `open`, (e.g. to open the bolt in addition to the latch), in this case, `payload_open` is required in the configuration. If the lock is in optimistic mode, it will change states to `unlocked` when handling the `open` command.
An MQTT lock can also report the intermediate states `unlocking`, `locking` or `jammed` if the motor reports a jammed state.
To enable MQTT locks in your installation, add the following to your {% term "`configuration.yaml`" %} file:
To use an MQTT lock in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
@ -30,6 +32,8 @@ mqtt:
command_topic: "home/frontdoor/set"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.

5
source/_integrations/notify.mqtt.markdown
View File

@ -12,6 +12,9 @@ The **MQTT notify** platform lets you send an MQTT message when the `send_messag
## Configuration
To use an MQTT notify entity in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
mqtt:
@ -19,6 +22,8 @@ mqtt:
command_topic: "home/living_room/status_screen/notifications"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.

5
source/_integrations/number.mqtt.markdown
View File

@ -12,7 +12,8 @@ The `mqtt` Number platform allows you to integrate devices that might expose con
## Configuration
To enable MQTT Number in your installation, add the following to your {% term "`configuration.yaml`" %} file:
To use an MQTT number entity in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
@ -21,6 +22,8 @@ mqtt:
command_topic: my-device/threshold
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.

5
source/_integrations/scene.mqtt.markdown
View File

@ -12,7 +12,8 @@ The `mqtt` scene platform lets you control your MQTT enabled scenes.
## Configuration
To enable a MQTT scene in your installation, add the following to your {% term "`configuration.yaml`" %} file:
To use an MQTT scene entity in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
@ -21,6 +22,8 @@ mqtt:
command_topic: zigbee2mqtt/living_room_group/set
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.

5
source/_integrations/select.mqtt.markdown
View File

@ -12,7 +12,8 @@ The `mqtt` Select platform allows you to integrate devices that might expose con
## Configuration
To enable MQTT Select in your installation, add the following to your {% term "`configuration.yaml`" %} file:
To use an MQTT select entity in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
@ -25,6 +26,8 @@ mqtt:
- "Option 2"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.

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

@ -12,7 +12,8 @@ This `mqtt` sensor platform uses the MQTT message payload as the sensor value. I
## Configuration
To use your MQTT sensor in your installation, add the following to your {% term "`configuration.yaml`" %} file:
To use an MQTT sensor in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
@ -22,6 +23,8 @@ mqtt:
state_topic: "home/bedroom/temperature"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.

5
source/_integrations/siren.mqtt.markdown
View File

@ -18,7 +18,8 @@ When a `state_topic` is not available, the siren will work in optimistic mode. I
Optimistic mode can be forced, even if the `state_topic` is available. Try to enable it, if experiencing incorrect operation.
To enable this siren in your installation, add the following to your {% term "`configuration.yaml`" %} file:
To use an MQTT siren in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
@ -27,6 +28,8 @@ mqtt:
command_topic: "home/bedroom/siren/set"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.

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

@ -18,7 +18,8 @@ When a `state_topic` is not available, the switch will work in optimistic mode.
Optimistic mode can be forced, even if the `state_topic` is available. Try to enable it, if experiencing incorrect switch operation.
To enable this switch in your installation, add the following to your {% term "`configuration.yaml`" %} file:
To use an MQTT switch in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
@ -27,6 +28,8 @@ mqtt:
command_topic: "home/bedroom/switch1/set"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.

5
source/_integrations/text.mqtt.markdown
View File

@ -12,7 +12,8 @@ The `mqtt` Text platform allows you to integrate devices that show text that can
## Configuration
To enable MQTT text platform in your installation, add the following to your {% term "`configuration.yaml`" %} file:
To use an MQTT text entity in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
@ -21,6 +22,8 @@ mqtt:
command_topic: command-topic
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.

5
source/_integrations/update.mqtt.markdown
View File

@ -12,7 +12,8 @@ The `mqtt` Update platform allows you to integrate devices that might expose fir
## Configuration
To enable MQTT Update in your installation, add the following to your {% term "`configuration.yaml`" %} file:
To use an MQTT update entity in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
@ -22,6 +23,8 @@ mqtt:
latest_version_topic: topic-latest
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.

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

@ -12,7 +12,18 @@ The initial state of the MQTT vacuum {% term entity %} will set to `unknown` and
## Configuration
MQTT vacuum configuration section.
To use an MQTT vacuum in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
mqtt:
- vacuum:
state_topic: state-topic
command_topic: command-topic
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:

25
source/_integrations/valve.mqtt.markdown
View File

@ -18,16 +18,19 @@ A valve entity can be have the following states: `open`, `opening`, `closed` or
If a `state_topic` is configured, the entity's state will be updated only after an MQTT message is received on `state_topic` matching `state_open`, `state_opening`, `state_closed` or `state_closing`. Commands configured through `payload_open`, `payload_closed`, and `payload_stop` will be published to `command_topic` to control the valve.
To use your MQTT valve in your installation, add the following to your {% term "`configuration.yaml`" %} file:
To use an MQTT valve in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry for a value that is set by open or close command
mqtt:
- valve:
command_topic: "home-assistant/valve/set"
state_topic: "home-assistant/valve/state"
command_topic: "heater/valve/set"
state_topic: "heater/valve/state"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
### Valve controlled by position
If the valve supports reporting its position (the `reports_position` config option is set to `true`), a numeric state is expected on `state_topic`, but state updates are still allowed for `state_opening` and `state_closing`. Also, a JSON format is supported. It allows both `state` and `position` to be reported together.
@ -46,8 +49,8 @@ To use your MQTT valve in your installation, add the following to your {% term "
# Example configuration.yaml entry for a valve that reports position
mqtt:
- valve:
command_topic: "home-assistant/valve/set"
state_topic: "home-assistant/valve/state"
command_topic: "heater/valve/set"
state_topic: "heater/valve/state"
reports_position: true
```
@ -311,10 +314,10 @@ mqtt:
- valve:
name: "MQTT valve"
command_template: '{"x": {{ value }} }'
command_topic: "home-assistant/valve/set"
state_topic: "home-assistant/valve/state"
command_topic: "heater/valve/set"
state_topic: "heater/valve/state"
availability:
- topic: "home-assistant/valve/availability"
- topic: "heater/valve/availability"
qos: 0
reports_position: false
retain: true
@ -345,10 +348,10 @@ mqtt:
- valve:
name: "MQTT valve"
command_template: '{"x": {{ value }} }'
command_topic: "home-assistant/valve/set"
state_topic: "home-assistant/valve/state"
command_topic: "heater/valve/set"
state_topic: "heater/valve/state"
availability:
- topic: "home-assistant/valve/availability"
- topic: "heater/valve/availability"
reports_position: true
value_template: "{{ value_json.x }}"
```

5
source/_integrations/water_heater.mqtt.markdown
View File

@ -12,7 +12,8 @@ The `mqtt` water heater platform lets you control your MQTT enabled water heater
## Configuration
To enable this water heater platform in your installation, first add the following to your {% term "`configuration.yaml`" %} file:
To use an MQTT water heater in your installation, add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
# Example configuration.yaml entry
@ -22,6 +23,8 @@ mqtt:
mode_command_topic: "basement/boiler/mode/set"
```
Alternatively, a more advanced approach is to set it up via [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.