From 6e96b63b9e3b44f772d4b77f7953170f40fe27a7 Mon Sep 17 00:00:00 2001 From: Jan Bouwhuis Date: Sat, 25 May 2024 01:30:26 +0200 Subject: [PATCH] Document mqtt state updates with empty or `None` values (#32864) --- source/_integrations/alarm_control_panel.mqtt.markdown | 2 +- source/_integrations/climate.mqtt.markdown | 8 ++++---- source/_integrations/cover.mqtt.markdown | 2 +- source/_integrations/device_tracker.mqtt.markdown | 2 +- source/_integrations/fan.mqtt.markdown | 2 +- source/_integrations/humidifier.mqtt.markdown | 2 +- source/_integrations/light.mqtt.markdown | 6 +++--- source/_integrations/lock.mqtt.markdown | 2 +- source/_integrations/number.mqtt.markdown | 2 +- source/_integrations/select.mqtt.markdown | 2 +- source/_integrations/siren.mqtt.markdown | 2 +- source/_integrations/switch.mqtt.markdown | 2 +- source/_integrations/valve.mqtt.markdown | 2 +- source/_integrations/water_heater.mqtt.markdown | 2 +- 14 files changed, 19 insertions(+), 19 deletions(-) diff --git a/source/_integrations/alarm_control_panel.mqtt.markdown b/source/_integrations/alarm_control_panel.mqtt.markdown index 4625ef66062..eaea1448d9c 100644 --- a/source/_integrations/alarm_control_panel.mqtt.markdown +++ b/source/_integrations/alarm_control_panel.mqtt.markdown @@ -246,7 +246,7 @@ retain: type: boolean default: false state_topic: - description: The MQTT topic subscribed to receive state updates. + description: The MQTT topic subscribed to receive state updates. A "None" payload resets to an `unknown` state. An empty payload is ignored. required: true type: string supported_features: diff --git a/source/_integrations/climate.mqtt.markdown b/source/_integrations/climate.mqtt.markdown index 89151e88934..2d7b1862042 100644 --- a/source/_integrations/climate.mqtt.markdown +++ b/source/_integrations/climate.mqtt.markdown @@ -29,8 +29,8 @@ action_template: type: template action_topic: description: >- - The MQTT topic to subscribe for changes of the current action. If this is set, the climate graph uses the value received as data source. - Valid values: `off`, `heating`, `cooling`, `drying`, `idle`, `fan`. + The MQTT topic to subscribe for changes of the current action. If this is set, the climate graph uses the value received as data source. A "None" payload resets the current action state. An empty payload is ignored. + Valid action values: `off`, `heating`, `cooling`, `drying`, `idle`, `fan`. required: false type: string availability: @@ -161,7 +161,7 @@ fan_mode_state_template: required: false type: template fan_mode_state_topic: - description: The MQTT topic to subscribe for changes of the HVAC fan mode. If this is not set, the fan mode works in optimistic mode (see below). + description: The MQTT topic to subscribe for changes of the HVAC fan mode. If this is not set, the fan mode works in optimistic mode (see below). A "None" payload resets the fan mode state. An empty payload is ignored. required: false type: string fan_modes: @@ -216,7 +216,7 @@ mode_state_template: required: false type: template mode_state_topic: - description: The MQTT topic to subscribe for changes of the HVAC operation mode. If this is not set, the operation mode works in optimistic mode (see below). + description: The MQTT topic to subscribe for changes of the HVAC operation mode. If this is not set, the operation mode works in optimistic mode (see below). A "None" payload resets to an `unknown` state. An empty payload is ignored. required: false type: string modes: diff --git a/source/_integrations/cover.mqtt.markdown b/source/_integrations/cover.mqtt.markdown index 5f06b361b76..800a758a74d 100644 --- a/source/_integrations/cover.mqtt.markdown +++ b/source/_integrations/cover.mqtt.markdown @@ -257,7 +257,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. + 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. required: false type: string tilt_closed_value: diff --git a/source/_integrations/device_tracker.mqtt.markdown b/source/_integrations/device_tracker.mqtt.markdown index ee7ad9ef7e2..45142726748 100644 --- a/source/_integrations/device_tracker.mqtt.markdown +++ b/source/_integrations/device_tracker.mqtt.markdown @@ -170,7 +170,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. + 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. required: false type: string unique_id: diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index e6a84090b2c..bcc3e01c521 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -291,7 +291,7 @@ speed_range_min: type: integer default: 1 state_topic: - description: The MQTT topic subscribed to receive state updates. + description: The MQTT topic subscribed to receive state updates. A "None" payload resets to an `unknown` state. An empty payload is ignored. required: false type: string state_value_template: diff --git a/source/_integrations/humidifier.mqtt.markdown b/source/_integrations/humidifier.mqtt.markdown index 4f5a4e5a8a7..376f852f75b 100644 --- a/source/_integrations/humidifier.mqtt.markdown +++ b/source/_integrations/humidifier.mqtt.markdown @@ -273,7 +273,7 @@ retain: type: boolean default: true state_topic: - description: The MQTT topic subscribed to receive state updates. + description: The MQTT topic subscribed to receive state updates. A "None" payload resets to an `unknown` state. An empty payload is ignored. required: false type: string state_value_template: diff --git a/source/_integrations/light.mqtt.markdown b/source/_integrations/light.mqtt.markdown index 31ee29164a1..3911011abf2 100644 --- a/source/_integrations/light.mqtt.markdown +++ b/source/_integrations/light.mqtt.markdown @@ -359,7 +359,7 @@ schema: type: string default: default state_topic: - description: The MQTT topic subscribed to receive state updates. + description: The MQTT topic subscribed to receive state updates. A "None" payload resets to an `unknown` state. An empty payload is ignored. required: false type: string state_value_template: @@ -706,7 +706,7 @@ schema: type: string default: default state_topic: - description: The MQTT topic subscribed to receive state updates. + description: The MQTT topic subscribed to receive state updates. A "None" payload resets to an `unknown` state. An empty payload is ignored. required: false type: string supported_color_modes: @@ -1069,7 +1069,7 @@ state_template: required: false type: template state_topic: - description: The MQTT topic subscribed to receive state updates. + description: The MQTT topic subscribed to receive state updates. A "None" payload resets to an `unknown` state. An empty payload is ignored. required: false type: string unique_id: diff --git a/source/_integrations/lock.mqtt.markdown b/source/_integrations/lock.mqtt.markdown index ea94daec7fc..4d9d8269828 100644 --- a/source/_integrations/lock.mqtt.markdown +++ b/source/_integrations/lock.mqtt.markdown @@ -223,7 +223,7 @@ state_locking: type: string default: LOCKING state_topic: - description: The MQTT topic subscribed to receive state updates. It accepts states configured with `state_jammed`, `state_locked`, `state_unlocked`, `state_locking` or `state_unlocking`. + description: The MQTT topic subscribed to receive state updates. It accepts states configured with `state_jammed`, `state_locked`, `state_unlocked`, `state_locking` or `state_unlocking`. A "None" payload resets to an `unknown` state. An empty payload is ignored. required: false type: string state_unlocked: diff --git a/source/_integrations/number.mqtt.markdown b/source/_integrations/number.mqtt.markdown index 1e7a5c29a3e..220cc1a6a65 100644 --- a/source/_integrations/number.mqtt.markdown +++ b/source/_integrations/number.mqtt.markdown @@ -181,7 +181,7 @@ retain: type: boolean default: false state_topic: - description: The MQTT topic subscribed to receive number values. + description: The MQTT topic subscribed to receive number values. An empty payload is ignored. required: false type: string step: diff --git a/source/_integrations/select.mqtt.markdown b/source/_integrations/select.mqtt.markdown index ea7271dbf5e..3e8317ae545 100644 --- a/source/_integrations/select.mqtt.markdown +++ b/source/_integrations/select.mqtt.markdown @@ -173,7 +173,7 @@ retain: type: boolean default: false state_topic: - description: The MQTT topic subscribed to receive update of the selected option. + description: The MQTT topic subscribed to receive update of the selected option. A "None" payload resets to an `unknown` state. An empty payload is ignored. required: false type: string unique_id: diff --git a/source/_integrations/siren.mqtt.markdown b/source/_integrations/siren.mqtt.markdown index 38a1877ea46..5a370c4f9f4 100644 --- a/source/_integrations/siren.mqtt.markdown +++ b/source/_integrations/siren.mqtt.markdown @@ -211,7 +211,7 @@ state_on: type: string default: "`payload_on` if defined, else `'ON'`" state_topic: - 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." + 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 update 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: diff --git a/source/_integrations/switch.mqtt.markdown b/source/_integrations/switch.mqtt.markdown index 09f382a7426..661d7bc5d34 100644 --- a/source/_integrations/switch.mqtt.markdown +++ b/source/_integrations/switch.mqtt.markdown @@ -202,7 +202,7 @@ state_on: type: string default: "`payload_on` if defined, else ON" state_topic: - description: The MQTT topic subscribed to receive state updates. + description: The MQTT topic subscribed to receive state updates. A "None" payload resets to an `unknown` state. An empty payload is ignored. required: false type: string unique_id: diff --git a/source/_integrations/valve.mqtt.markdown b/source/_integrations/valve.mqtt.markdown index 5c546886b98..96662a5d1ab 100644 --- a/source/_integrations/valve.mqtt.markdown +++ b/source/_integrations/valve.mqtt.markdown @@ -264,7 +264,7 @@ state_opening: type: string default: opening state_topic: - description: The MQTT topic subscribed to receive valve state messages. State topic accepts a state payload (`open`, `opening`, `closed`, or `closing`) or, if `reports_position` is supported, a numeric value representing the position. In a JSON format with variables `state` and `position` both values can received together. + description: The MQTT topic subscribed to receive valve state messages. State topic accepts a state payload (`open`, `opening`, `closed`, or `closing`) or, if `reports_position` is supported, a numeric value representing the position. In a JSON format with variables `state` and `position` both values can received together. A "None" state value resets to an `unknown` state. An empty string is ignored. required: false type: string unique_id: diff --git a/source/_integrations/water_heater.mqtt.markdown b/source/_integrations/water_heater.mqtt.markdown index c7d81b811af..13fc7706be3 100644 --- a/source/_integrations/water_heater.mqtt.markdown +++ b/source/_integrations/water_heater.mqtt.markdown @@ -167,7 +167,7 @@ mode_state_template: required: false type: template mode_state_topic: - description: The MQTT topic to subscribe for changes of the water heater operation mode. If this is not set, the operation mode works in optimistic mode (see below). + description: The MQTT topic to subscribe for changes of the water heater operation mode. If this is not set, the operation mode works in optimistic mode (see below). A "None" payload resets to an `unknown` state. An empty payload is ignored. required: false type: string modes: