mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-21 16:27:19 +00:00
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:
parent
896af73d54
commit
f1ce652830
@ -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:
|
||||
|
@ -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:
|
||||
|
@ -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:
|
||||
|
@ -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:
|
||||
|
@ -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:
|
||||
|
@ -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:
|
||||
|
@ -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 %}
|
||||
|
@ -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"
|
||||
|
Loading…
x
Reference in New Issue
Block a user