diff --git a/source/_integrations/alarm_control_panel.mqtt.markdown b/source/_integrations/alarm_control_panel.mqtt.markdown index 34a8c53c8db..05445561fd2 100644 --- a/source/_integrations/alarm_control_panel.mqtt.markdown +++ b/source/_integrations/alarm_control_panel.mqtt.markdown @@ -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: diff --git a/source/_integrations/binary_sensor.mqtt.markdown b/source/_integrations/binary_sensor.mqtt.markdown index 4899572be9b..b791220e774 100644 --- a/source/_integrations/binary_sensor.mqtt.markdown +++ b/source/_integrations/binary_sensor.mqtt.markdown @@ -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: diff --git a/source/_integrations/cover.mqtt.markdown b/source/_integrations/cover.mqtt.markdown index 6c093b95415..bdf32a63c2b 100644 --- a/source/_integrations/cover.mqtt.markdown +++ b/source/_integrations/cover.mqtt.markdown @@ -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: diff --git a/source/_integrations/device_tracker.mqtt.markdown b/source/_integrations/device_tracker.mqtt.markdown index 625f1c56405..e36c0db84ba 100644 --- a/source/_integrations/device_tracker.mqtt.markdown +++ b/source/_integrations/device_tracker.mqtt.markdown @@ -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: diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index afe35bebd41..e55468f9bd0 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -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: diff --git a/source/_integrations/humidifier.mqtt.markdown b/source/_integrations/humidifier.mqtt.markdown index ad043a83901..7e228d764e9 100644 --- a/source/_integrations/humidifier.mqtt.markdown +++ b/source/_integrations/humidifier.mqtt.markdown @@ -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: diff --git a/source/_integrations/light.mqtt.markdown b/source/_integrations/light.mqtt.markdown index e9179af08c9..4811d924e0d 100644 --- a/source/_integrations/light.mqtt.markdown +++ b/source/_integrations/light.mqtt.markdown @@ -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 %} diff --git a/source/_integrations/switch.mqtt.markdown b/source/_integrations/switch.mqtt.markdown index c3619c78b2d..b413675da0b 100644 --- a/source/_integrations/switch.mqtt.markdown +++ b/source/_integrations/switch.mqtt.markdown @@ -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"