Improve the documentation on the accepted states on state_topic for MQTT entities (#35197)

* Improve the documentation on the accepted states on `state_topic` for MQTT entities

* FIx formatting

* Follow up on code review

* Color attribute explain formatting

* Use json example

* More follow up
This commit is contained in:
Jan Bouwhuis 2024-10-13 07:21:46 +02:00 committed by GitHub
parent 896af73d54
commit f1ce652830
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 39 additions and 13 deletions

View File

@ -250,7 +250,7 @@ retain:
type: boolean
default: false
state_topic:
description: The MQTT topic subscribed to receive state updates. A "None" payload resets to an `unknown` state. An empty payload is ignored.
description: "The MQTT topic subscribed to receive state updates. A \"None\" payload resets to an `unknown` state. An empty payload is ignored. Valid state payloads are: `armed_away`, `armed_custom_bypass`, `armed_home`, `armed_night`, `armed_vacation`, `arming`, `disarmed`, `disarming` `pending` and `triggered`."
required: true
type: string
supported_features:

View File

@ -198,7 +198,7 @@ qos:
type: integer
default: 0
state_topic:
description: The MQTT topic subscribed to receive sensor's state.
description: The MQTT topic subscribed to receive sensor's state. Valid states are `OFF` and `ON`. Custom `OFF` and `ON` values can be set with the `payload_off` and `payload_on` config options.
required: true
type: string
unique_id:

View File

@ -261,7 +261,7 @@ state_stopped:
type: string
default: stopped
state_topic:
description: The MQTT topic subscribed to receive cover state messages. State topic can only read (`open`, `opening`, `closed`, `closing` or `stopped`) state. A "None" payload resets to an `unknown` state. An empty payload is ignored.
description: The MQTT topic subscribed to receive cover state messages. State topic can only read a (`open`, `opening`, `closed`, `closing` or `stopped`) state. A "None" payload resets to an `unknown` state. An empty payload is ignored.
required: false
type: string
tilt_closed_value:

View File

@ -177,7 +177,7 @@ source_type:
required: false
type: string
state_topic:
description: The MQTT topic subscribed to receive device tracker state changes. The states defined in `state_topic` override the location states defined by the `json_attributes_topic`. This state override is turned inactive if the `state_topic` receives a message containing `payload_reset`. The `state_topic` can only be omitted if `json_attributes_topic` is used. An empty payload is ignored.
description: The MQTT topic subscribed to receive device tracker state changes. The states defined in `state_topic` override the location states defined by the `json_attributes_topic`. This state override is turned inactive if the `state_topic` receives a message containing `payload_reset`. The `state_topic` can only be omitted if `json_attributes_topic` is used. An empty payload is ignored. Valid payloads are `not_home`, `home` or any other custom location or zone name. Payloads for `not_home`, `home` can be overridden with the `payload_not_home`and `payload_home` config options.
required: false
type: string
unique_id:

View File

@ -296,7 +296,7 @@ speed_range_min:
type: integer
default: 1
state_topic:
description: The MQTT topic subscribed to receive state updates. A "None" payload resets to an `unknown` state. An empty payload is ignored.
description: The MQTT topic subscribed to receive state updates. A "None" payload resets to an `unknown` state. An empty payload is ignored. By default, valid state payloads are `OFF` and `ON`. The accepted payloads can be overridden with the `payload_off` and `payload_on` config options.
required: false
type: string
state_value_template:

View File

@ -277,7 +277,7 @@ retain:
type: boolean
default: true
state_topic:
description: The MQTT topic subscribed to receive state updates. A "None" payload resets to an `unknown` state. An empty payload is ignored.
description: The MQTT topic subscribed to receive state updates. A "None" payload resets to an `unknown` state. An empty payload is ignored. Valid state payloads are `OFF` and `ON`. Custom `OFF` and `ON` values can be set with the `payload_off` and `payload_on` config options.
required: false
type: string
state_value_template:

View File

@ -363,11 +363,11 @@ schema:
type: string
default: default
state_topic:
description: The MQTT topic subscribed to receive state updates. A "None" payload resets to an `unknown` state. An empty payload is ignored.
description: "The MQTT topic subscribed to receive state updates. A \"None\" payload resets to an `unknown` state. An empty payload is ignored. By default, valid state payloads are `OFF` and `ON`. The accepted payloads can be overridden with the `payload_off` and `payload_on` config options."
required: false
type: string
state_value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the state value. The template should return the `payload_on` and `payload_off` values, so if your light uses `power on` to turn on, your `state_value_template` string should return `power on` when the switch is on. For example, if the message is just `on`, your `state_value_template` should be `power {{ value }}`. When your `payload_on = 27`, `payload_off = 'off'`, then this template might be `'off' if value_json.my_custom_brightness_field <= 0 else 27`."
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the state value. The template should return the `payload_on` and `payload_off` values, so if your light uses `power on` to turn on, your `state_value_template` string should return `power on` when the switch is on. For example, if the message is just `on`, your `state_value_template` should be `power {{ value }}`. When your `payload_on = 27` and `payload_off = 'off'`, then this template might be `'off' if value_json.my_custom_brightness_field <= 0 else 27`."
required: false
type: template
unique_id:
@ -708,7 +708,7 @@ schema:
type: string
default: default
state_topic:
description: The MQTT topic subscribed to receive state updates. A "None" payload resets to an `unknown` state. An empty payload is ignored.
description: 'The MQTT topic subscribed to receive state updates in a JSON-format. The JSON payload may contain the elements: `"state"`: `"ON"` the light is on, `"OFF"` the light is off, `null` the state is `unknown`; `"color_mode"`: one of the `supported_color_modes`; `"color"`: A dict with the color attributes*; `"brightness"`: The brightness; `"color_temp"`: The color temperature; `"effect"`: The effect of the light.'
required: false
type: string
supported_color_modes:
@ -726,6 +726,32 @@ white_scale:
default: 255
{% endconfiguration %}
*The `color` attribute dict in the JSON state payload should contain the following keys based on the `color_mode`:
- `hs`:
- `h`: The hue value
- `s`: The saturation value
- `xy`:
- `x`: X color value
- `y`: Y color value
- `rgb`:
- `r`: Red color value
- `g`: Green color value
- `b`: Blue color value
- `rgbw`:
- `r`: Red color value
- `g`: Green color value
- `b`: Blue color value
- `w`: White value
- `rgbww`:
- `r`: Red color value
- `g`: Green color value
- `b`: Blue color value
- `c`: Cool white value
- `w`: Warm white value
More details about the different colors, color modes and range values [can be found here](https://www.home-assistant.io/integrations/light/).
{% important %}
Make sure that your topics match exact. `some-topic/` and `some-topic` are different topics.
{% endimportant %}

View File

@ -203,14 +203,14 @@ state_off:
description: The payload that represents the `off` state. Used when value that represents `off` state in the `state_topic` is different from value that should be sent to the `command_topic` to turn the device `off`.
required: false
type: string
default: "`payload_off` if defined, else OFF"
default: "`payload_off` if defined, else `OFF`"
state_on:
description: The payload that represents the `on` state. Used when value that represents `on` state in the `state_topic` is different from value that should be sent to the `command_topic` to turn the device `on`.
required: false
type: string
default: "`payload_on` if defined, else ON"
default: "`payload_on` if defined, else `ON`"
state_topic:
description: The MQTT topic subscribed to receive state updates. A "None" payload resets to an `unknown` state. An empty payload is ignored.
description: The MQTT topic subscribed to receive state updates. A "None" payload resets to an `unknown` state. An empty payload is ignored.By default, valid state payloads are `OFF` and `ON`. The accepted payloads can be overridden with the `payload_off` and `payload_on` config options.
required: false
type: string
unique_id:
@ -260,7 +260,7 @@ For a check, you can use the command line tools `mosquitto_pub` shipped with `mo
mosquitto_pub -h 127.0.0.1 -t home/bedroom/switch1/available -m "online"
```
We can simulate the switch being turned on by publishing the "ON" command message:
We can simulate the switch being turned on by publishing the `ON` command message:
```bash
mosquitto_pub -h 127.0.0.1 -t home/bedroom/switch1/set -m "ON"