From 14cefb3868d34ed4e167f0a687f92b74b8d0699f Mon Sep 17 00:00:00 2001 From: Jan Bouwhuis Date: Thu, 10 Jul 2025 06:41:58 +0200 Subject: [PATCH] Consequent documentation of MQTT entity set up (#39951) --- .../alarm_control_panel.mqtt.markdown | 4 ++- .../_integrations/binary_sensor.mqtt.markdown | 12 +++++---- source/_integrations/button.mqtt.markdown | 5 ++++ source/_integrations/camera.mqtt.markdown | 5 +++- source/_integrations/climate.mqtt.markdown | 4 ++- source/_integrations/cover.mqtt.markdown | 5 +++- .../device_tracker.mqtt.markdown | 5 +++- source/_integrations/event.mqtt.markdown | 5 ++++ source/_integrations/fan.mqtt.markdown | 4 ++- source/_integrations/humidifier.mqtt.markdown | 5 +++- source/_integrations/image.mqtt.markdown | 5 +++- source/_integrations/lawn_mower.mqtt.markdown | 5 +++- source/_integrations/light.mqtt.markdown | 15 +++++++++++ source/_integrations/lock.mqtt.markdown | 6 ++++- source/_integrations/notify.mqtt.markdown | 5 ++++ source/_integrations/number.mqtt.markdown | 5 +++- source/_integrations/scene.mqtt.markdown | 5 +++- source/_integrations/select.mqtt.markdown | 5 +++- source/_integrations/sensor.mqtt.markdown | 5 +++- source/_integrations/siren.mqtt.markdown | 5 +++- source/_integrations/switch.mqtt.markdown | 5 +++- source/_integrations/text.mqtt.markdown | 5 +++- source/_integrations/update.mqtt.markdown | 5 +++- source/_integrations/vacuum.mqtt.markdown | 13 +++++++++- source/_integrations/valve.mqtt.markdown | 25 +++++++++++-------- .../_integrations/water_heater.mqtt.markdown | 5 +++- 26 files changed, 137 insertions(+), 36 deletions(-) diff --git a/source/_integrations/alarm_control_panel.mqtt.markdown b/source/_integrations/alarm_control_panel.mqtt.markdown index 10a55d74967..a51036fdb08 100644 --- a/source/_integrations/alarm_control_panel.mqtt.markdown +++ b/source/_integrations/alarm_control_panel.mqtt.markdown @@ -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`. diff --git a/source/_integrations/binary_sensor.mqtt.markdown b/source/_integrations/binary_sensor.mqtt.markdown index 5b7f8a1be0f..658c06c9db8 100644 --- a/source/_integrations/binary_sensor.mqtt.markdown +++ b/source/_integrations/binary_sensor.mqtt.markdown @@ -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 diff --git a/source/_integrations/button.mqtt.markdown b/source/_integrations/button.mqtt.markdown index 8cda3240c31..bb34e8b10c5 100644 --- a/source/_integrations/button.mqtt.markdown +++ b/source/_integrations/button.mqtt.markdown @@ -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`. diff --git a/source/_integrations/camera.mqtt.markdown b/source/_integrations/camera.mqtt.markdown index 32b8827f32a..774255931fc 100644 --- a/source/_integrations/camera.mqtt.markdown +++ b/source/_integrations/camera.mqtt.markdown @@ -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 diff --git a/source/_integrations/climate.mqtt.markdown b/source/_integrations/climate.mqtt.markdown index 6d13385fa05..9ac0650c114 100644 --- a/source/_integrations/climate.mqtt.markdown +++ b/source/_integrations/climate.mqtt.markdown @@ -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. diff --git a/source/_integrations/cover.mqtt.markdown b/source/_integrations/cover.mqtt.markdown index 61e61ca4313..599de44065b 100644 --- a/source/_integrations/cover.mqtt.markdown +++ b/source/_integrations/cover.mqtt.markdown @@ -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`." diff --git a/source/_integrations/device_tracker.mqtt.markdown b/source/_integrations/device_tracker.mqtt.markdown index 5efd902efbf..db3627de042 100644 --- a/source/_integrations/device_tracker.mqtt.markdown +++ b/source/_integrations/device_tracker.mqtt.markdown @@ -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`. diff --git a/source/_integrations/event.mqtt.markdown b/source/_integrations/event.mqtt.markdown index 07f0ae45700..b6dfc759b35 100644 --- a/source/_integrations/event.mqtt.markdown +++ b/source/_integrations/event.mqtt.markdown @@ -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`. diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index 5cb84cbcd0a..32a0e5601ea 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -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`. diff --git a/source/_integrations/humidifier.mqtt.markdown b/source/_integrations/humidifier.mqtt.markdown index e82c0821ec6..a1f5b73d507 100644 --- a/source/_integrations/humidifier.mqtt.markdown +++ b/source/_integrations/humidifier.mqtt.markdown @@ -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. diff --git a/source/_integrations/image.mqtt.markdown b/source/_integrations/image.mqtt.markdown index 7ff40d7cb14..966a4ca9533 100644 --- a/source/_integrations/image.mqtt.markdown +++ b/source/_integrations/image.mqtt.markdown @@ -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`. diff --git a/source/_integrations/lawn_mower.mqtt.markdown b/source/_integrations/lawn_mower.mqtt.markdown index e75bb881fcc..31bef5ed88a 100644 --- a/source/_integrations/lawn_mower.mqtt.markdown +++ b/source/_integrations/lawn_mower.mqtt.markdown @@ -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`. diff --git a/source/_integrations/light.mqtt.markdown b/source/_integrations/light.mqtt.markdown index 46e87b11641..c7e9f679729 100644 --- a/source/_integrations/light.mqtt.markdown +++ b/source/_integrations/light.mqtt.markdown @@ -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`. diff --git a/source/_integrations/lock.mqtt.markdown b/source/_integrations/lock.mqtt.markdown index 1611a73e3fe..9d0256fac13 100644 --- a/source/_integrations/lock.mqtt.markdown +++ b/source/_integrations/lock.mqtt.markdown @@ -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`. diff --git a/source/_integrations/notify.mqtt.markdown b/source/_integrations/notify.mqtt.markdown index b13408aa52a..d2a3979701a 100644 --- a/source/_integrations/notify.mqtt.markdown +++ b/source/_integrations/notify.mqtt.markdown @@ -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`. diff --git a/source/_integrations/number.mqtt.markdown b/source/_integrations/number.mqtt.markdown index 8ae647a4b36..334d836371e 100644 --- a/source/_integrations/number.mqtt.markdown +++ b/source/_integrations/number.mqtt.markdown @@ -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`. diff --git a/source/_integrations/scene.mqtt.markdown b/source/_integrations/scene.mqtt.markdown index ea0b9f5560f..cba0d10b950 100644 --- a/source/_integrations/scene.mqtt.markdown +++ b/source/_integrations/scene.mqtt.markdown @@ -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`. diff --git a/source/_integrations/select.mqtt.markdown b/source/_integrations/select.mqtt.markdown index 68af312e19c..c9f91d1e08b 100644 --- a/source/_integrations/select.mqtt.markdown +++ b/source/_integrations/select.mqtt.markdown @@ -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`. diff --git a/source/_integrations/sensor.mqtt.markdown b/source/_integrations/sensor.mqtt.markdown index a6063810954..557883df6ae 100644 --- a/source/_integrations/sensor.mqtt.markdown +++ b/source/_integrations/sensor.mqtt.markdown @@ -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`. diff --git a/source/_integrations/siren.mqtt.markdown b/source/_integrations/siren.mqtt.markdown index 730e2b5dead..8a9566c60bf 100644 --- a/source/_integrations/siren.mqtt.markdown +++ b/source/_integrations/siren.mqtt.markdown @@ -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`. diff --git a/source/_integrations/switch.mqtt.markdown b/source/_integrations/switch.mqtt.markdown index c8b9b39fa22..08da18b81cd 100644 --- a/source/_integrations/switch.mqtt.markdown +++ b/source/_integrations/switch.mqtt.markdown @@ -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`. diff --git a/source/_integrations/text.mqtt.markdown b/source/_integrations/text.mqtt.markdown index 496f067c8e6..d828ec31bb4 100644 --- a/source/_integrations/text.mqtt.markdown +++ b/source/_integrations/text.mqtt.markdown @@ -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`. diff --git a/source/_integrations/update.mqtt.markdown b/source/_integrations/update.mqtt.markdown index 17cdfdbbf53..2b485d8ee56 100644 --- a/source/_integrations/update.mqtt.markdown +++ b/source/_integrations/update.mqtt.markdown @@ -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`. diff --git a/source/_integrations/vacuum.mqtt.markdown b/source/_integrations/vacuum.mqtt.markdown index fc336fac5b8..3c97fd4283d 100644 --- a/source/_integrations/vacuum.mqtt.markdown +++ b/source/_integrations/vacuum.mqtt.markdown @@ -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: diff --git a/source/_integrations/valve.mqtt.markdown b/source/_integrations/valve.mqtt.markdown index 198418b6407..8f96fbc9251 100644 --- a/source/_integrations/valve.mqtt.markdown +++ b/source/_integrations/valve.mqtt.markdown @@ -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 }}" ``` diff --git a/source/_integrations/water_heater.mqtt.markdown b/source/_integrations/water_heater.mqtt.markdown index 0919a7c6c33..990979e8217 100644 --- a/source/_integrations/water_heater.mqtt.markdown +++ b/source/_integrations/water_heater.mqtt.markdown @@ -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`.