Improve MQTT siren documentation (#22958)

Co-authored-by: Franck Nijhof <git@frenck.dev>
This commit is contained in:
Erik Montnemery 2022-06-02 10:50:22 +02:00 committed by GitHub
parent d6dece293c
commit a07d85d91e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -87,15 +87,16 @@ available_tones:
required: false
type: list
command_template:
description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `command_topic`. The variable `value` will be assigned with the configured `payload_on` or `payload_off` setting. The siren turn on service parameters `tone`, `volume_level` or `duration` can be used as variables in the template. When operation in optimistic mode the corresponding state attributes will be set. Turn parameters will be filtered if a device misses the support.
description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate a custom payload to send to `command_topic`. The variable `value` will be assigned with the configured `payload_on` or `payload_off` setting. The siren turn on service parameters `tone`, `volume_level` or `duration` can be used as variables in the template. When operation in optimistic mode the corresponding state attributes will be set. Turn on parameters will be filtered if a device misses the support.
required: false
type: template
command_off_template:
description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `command_topic` when the siren turn off service is called. By default `command_template` will be used as template for service turn off. The variable `value` will be assigned with the configured `payload_off` setting.
description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate a custom payload to send to `command_topic` when the siren turn off service is called. By default `command_template` will be used as template for service turn off. The variable `value` will be assigned with the configured `payload_off` setting.
required: false
type: template
command_topic:
description: The MQTT topic to publish commands to change the siren state. Without command template a JSON payload is published. When the siren turn on service is called, the startup parameters will be added to the JSON payload. The `state` value of the JSON payload will be set to the the `payload_on` or `payload_off` configured payload.
description: >
The MQTT topic to publish commands to change the siren state. Without command templates, a default JSON payload like `{"state":"ON", "tone": "bell", "duration": 10, "volume_level": 0.5 }` is published. When the siren turn on service is called, the startup parameters will be added to the JSON payload. The `state` value of the JSON payload will be set to the the `payload_on` or `payload_off` configured payload.
required: false
type: string
device:
@ -221,7 +222,7 @@ state_on:
type: string
default: "`payload_on` if defined, else `'ON'`"
state_topic:
description: "The MQTT topic subscribed to receive state updates. When a JSON payload is detected, the `state` value of the JSON payload should supply the `payload_on` or `payload_off` defined payload to turn the siren on or off. Additional the state attributes `duration`, `tone` and `volume_level` can be updated. Use `value_template` to update render custom payload to a compliant JSON payload. Attributes will only be set if the function is supported by the device and a valid value is supplied. The initial state will be `unknown`. The state will be reset to `unknown` if a `None` payload or `null` JSON value is received as a state update."
description: "The MQTT topic subscribed to receive state updates. The state update may be either JSON or a simple string. When a JSON payload is detected, the `state` value of the JSON payload should supply the `payload_on` or `payload_off` defined payload to turn the siren on or off. Additionally, the state attributes `duration`, `tone` and `volume_level` can be updated. Use `value_template` to transform the received state udpate to a compliant JSON payload. Attributes will only be set if the function is supported by the device and a valid value is supplied. When a non JSON payload is detected, it should be either of the `payload_on` or `payload_off` defined payloads or `None` to reset the siren's state to `unknown`. The initial state will be `unknown`. The state will be reset to `unknown` if a `None` payload or `null` JSON value is received as a state update."
required: false
type: string
state_value_template:
@ -284,6 +285,31 @@ mqtt:
{% endraw %}
### On/Off only siren controlling a Tasmota relay
The example below shows a configuration for an On/Off type siren, which does not accept JSON commands.
{% raw %}
```yaml
# Example configuration.yaml entry
mqtt:
siren:
- unique_id: tasmota_siren
name: "garage"
state_topic: "stat/SIREN/RESULT"
command_topic: "cmnd/SIREN/POWER"
availability_topic: "tele/SIREN/LWT"
command_template: "{{ value }}"
state_value_template: "{{ value_json.POWER }}"
payload_on: "ON"
payload_off: "OFF"
payload_available: "Online"
payload_not_available: "Offline"
```
{% endraw %}
For a check, you can use the command line tools `mosquitto_pub` shipped with `mosquitto` to send MQTT messages. This allows you to operate your siren manually:
```bash