diff --git a/source/_conditions/humidity.is_value.markdown b/source/_conditions/humidity.is_value.markdown index fe04ed99b454..3c68816f8ae0 100644 --- a/source/_conditions/humidity.is_value.markdown +++ b/source/_conditions/humidity.is_value.markdown @@ -13,38 +13,18 @@ When you target more than one entity, the condition's **Condition passes if** op {% include conditions/ui_header.md %} -To use **Relative humidity** in an automation: - -1. Go to {% my automations title="**Settings** > **Automations & scenes**" %}. -2. Open an existing automation, or select **Create automation** > **Create new automation**. -3. In the **And if** section, select **Add condition**. -4. Select what you want to check. Under **By target** (see [Targets](#targets)), pick the area your humidity sensor is in (like your bedroom or bathroom). You can also select a device, a specific entity, or a label. -5. From the conditions shown for that target, select **Relative humidity**. -6. Under **Threshold type**, set the humidity level the condition checks against: - 1. Pick whether the reading must be **Above**, **Below**, **In range**, or **Outside range** of the threshold. - 2. Select **Number** or **Entity**: - - **Number**: Enter a fixed percentage directly, for example `65` for 65%. For **In range** or **Outside range**, enter both a lower and upper bound. - - **Entity**: Use a sensor entity or a [number helper](/integrations/input_number/) entity as the threshold: - - Number helper: You can adjust the threshold value without editing the automation. The sensor reading is compared against the number helper's current value. - - Sensor: Its current reading becomes the threshold and updates automatically as the sensor changes. This is useful for comparing two humidity readings, for example to check whether indoor humidity is higher than outdoor humidity. - - For **In range** or **Outside range**, you need two entities: one for the lower bound and one for the upper bound (for example, two separate number helpers). - - If you don't have a number helper, you can create one by selecting **Create a new number helper**. -7. Under **Condition passes if** (see [Behavior](#behavior-with-multiple-targets)), pick **Any** or **All**. -8. Select **Save**. +{% include conditions/threshold_value_steps.md + title="Relative humidity" + sensor="humidity sensor" + areas="bedroom or bathroom" + reading="humidity" + value_long="a fixed percentage directly, for example `65` for 65%" %} ### Options in the UI -{% options_ui %} -Threshold type: - description: | - The humidity level the entity has to meet for the condition to pass. **Above** and **Below** are exclusive: a reading equal to the threshold does not pass. **In range** is exclusive at both bounds. **Outside range** is inclusive: a reading equal to either bound passes. Choose **Number** to enter a fixed percentage (0–100), or **Entity** to use a sensor or number helper as a dynamic threshold. -Condition passes if: - description: | - When multiple entities are targeted, controls how results combine: - - - **Any**: The condition passes if at least one targeted entity meets the threshold (default). - - **All**: The condition passes only when every targeted entity meets the threshold. -{% endoptions_ui %} +{% include conditions/threshold_value_options_ui.md + reading="humidity" + value_short="a fixed percentage (0–100)" %} {% include conditions/yaml_header.md %} @@ -140,29 +120,10 @@ This passes when the bedroom humidity sensor reads above the number helper´s va ### Options in YAML -{% options_yaml %} -threshold: - description: | - The humidity level the entity has to meet for the condition to pass: - - - `type: above` (exclusive): Sets a minimum. The reading must be strictly above the threshold to pass. Provide `value` with a `number` key (0–100) or an `entity` key. - - `type: below` (exclusive): Sets a maximum. The reading must be strictly below the threshold to pass. Provide `value` with a `number` key (0–100) or an `entity` key. - - `type: between` (exclusive): Defines a range. The reading must be strictly between both bounds to pass. Provide `value_min` and `value_max`, each with a `number` key or an `entity` key. - - `type: outside` (inclusive): Defines an outside-range. The reading must be at or beyond either bound to pass. Provide `value_min` and `value_max`, each with a `number` key or an `entity` key. - - For the `number` key, use a percentage value (0–100). For the `entity` key, use an `input_number`, `number`, or `sensor` entity. - required: false - type: map -behavior: - description: | - When multiple entities are targeted, controls how results combine: - - - `any`: The condition passes if at least one targeted entity meets the threshold. - - `all`: The condition passes only when every targeted entity meets the threshold. - required: false - type: string - default: any -{% endoptions_yaml %} +{% include conditions/threshold_value_options_yaml.md + reading="humidity" + range_note="0–100" + number_final="a percentage value (0–100)" %} {% include conditions/targets.md %} diff --git a/source/_conditions/temperature.is_value.markdown b/source/_conditions/temperature.is_value.markdown index 224993190816..f748a82ae190 100644 --- a/source/_conditions/temperature.is_value.markdown +++ b/source/_conditions/temperature.is_value.markdown @@ -13,38 +13,25 @@ When you target more than one entity, the condition's **Condition passes if** op {% include conditions/ui_header.md %} -To use **Temperature** in an automation: - -1. Go to {% my automations title="**Settings** > **Automations & scenes**" %}. -2. Open an existing automation, or select **Create automation** > **Create new automation**. -3. In the **And if** section, select **Add condition**. -4. Select what you want to check. Under **By target** (see [Targets](#targets)), pick the area your temperature sensor is in (like your bedroom or living room). You can also select a device, a specific entity, or a label. -5. From the conditions shown for that target, select **Temperature value**. -6. Under **Threshold type**, set the temperature level the condition checks against: - 1. Pick whether the reading must be **Above**, **Below**, **In range**, or **Outside range** of the threshold. - 2. Select **Number** or **Entity**: - - **Number**: Enter a fixed temperature directly, for example `20` for 20°C. For **In range** or **Outside range**, enter both a lower and upper bound. - - **Entity**: Use a sensor entity or a [number helper](/integrations/input_number/) entity as the threshold: - - Number helper: You can adjust the threshold value without editing the automation. The sensor reading is compared against the number helper's current value. - - Sensor: Its current reading becomes the threshold and updates automatically as the sensor changes. This is useful for comparing two temperature readings, for example to check whether indoor temperature is higher than outdoor temperature. - - For **In range** or **Outside range**, you need two entities: one for the lower bound and one for the upper bound (for example, two separate number helpers). - - If you don't have a number helper, you can create one by selecting **Create a new number helper**. -7. Under **Unit**, select the temperature unit (°C or °F) to use for the threshold comparison. -8. Under **Condition passes if** (see [Behavior](#behavior-with-multiple-targets)), pick **Any** or **All**. -9. Select **Save**. +{% include conditions/threshold_value_steps.md + title="Temperature value" + sensor="temperature sensor" + areas="bedroom or living room" + reading="temperature" + value_long="a fixed temperature directly, for example `20` for 20°C" + has_unit="true" + unit_label="temperature unit" + unit_options="°C or °F" %} ### Options in the UI -{% options_ui %} -Threshold type: - description: | - The temperature level the entity has to meet for the condition to pass. **Above** and **Below** are exclusive: a reading equal to the threshold does not pass. **In range** is exclusive at both bounds. **Outside range** is inclusive: a reading equal to either bound passes. Choose **Number** to enter a fixed temperature value, or **Entity** to use a sensor or number helper as a dynamic threshold. -Unit: - description: The temperature unit to use for threshold comparison. Accepts `°C` or `°F`. Required when using numerical thresholds (not required when using entity references). - default: °C -Condition passes if: - description: When multiple entities are targeted, controls how results combine. Pick **Any** to pass if at least one targeted entity meets the threshold, or **All** to pass only when every targeted entity does. Default is **Any**. -{% endoptions_ui %} +{% include conditions/threshold_value_options_ui.md + reading="temperature" + value_short="a fixed temperature value" + has_unit="true" + unit_label="temperature unit" + unit_options_code="`°C` or `°F`" + unit_default="°C" %} {% include conditions/yaml_header.md %} @@ -107,38 +94,13 @@ This passes when the living room temperature sensor reads between 20 and 22°C. ### Options in YAML -{% options_yaml %} -threshold: - description: | - The temperature level the entity has to meet for the condition to pass: - - - `type: above` (exclusive): Sets a minimum. The reading must be strictly above the threshold to pass. - - `type: below` (exclusive): Sets a maximum. The reading must be strictly below the threshold to pass. - - `type: between` (exclusive): Defines a range. The reading must be strictly between both bounds to pass. - - `type: outside` (inclusive): Defines an outside-range. The reading must be at or beyond either bound to pass. - - For `type: above` and `type: below`, use `value` with either `number` and `unit_of_measurement`, or `entity`. For `type: between` and `type: outside`, use `value_min` and `value_max`, each with either `number` and `unit_of_measurement`, or `entity`. For example: - - ```yaml - threshold: - type: between - value_min: - entity: input_number.comfort_temperature_min - value_max: - number: 22 - unit_of_measurement: °C - ``` - - When using an `entity`, its current reading is used as the threshold at the moment the condition is evaluated, which lets you compare two temperature readings dynamically. - required: true - type: map -behavior: - description: > - Controls how results combine when multiple entities are targeted. Accepts `all` or `any`. - required: false - type: string - default: any -{% endoptions_yaml %} +{% include conditions/threshold_value_options_yaml.md + reading="temperature" + has_unit="true" + unit_default="°C" + unit_example_entity="input_number.comfort_temperature_min" + unit_example_value="22" + threshold_required="true" %} {% include conditions/targets.md %} diff --git a/source/_includes/conditions/threshold_value_options_ui.md b/source/_includes/conditions/threshold_value_options_ui.md new file mode 100644 index 000000000000..9ab21c3c1e9c --- /dev/null +++ b/source/_includes/conditions/threshold_value_options_ui.md @@ -0,0 +1,29 @@ +{% comment %} +Reusable "Options in the UI" block for entity conditions that test a reading +against the threshold-mapping schema. + +Parameters: + reading quantity noun, e.g. "humidity" + value_short Number-entry phrasing, e.g. "a fixed percentage (0–100)" + has_unit set (to anything) to add a "Unit" row (requires unit_label, + unit_options_code, unit_default) + unit_label unit-kind label, e.g. "temperature unit", "energy unit" + unit_options_code inline-code list of allowed units, e.g. "`°C` or `°F`" + unit_default default unit, e.g. "°C" +{% endcomment %} +{% options_ui %} +Threshold type: + description: | + The {{ include.reading }} level the entity has to meet for the condition to pass. **Above** and **Below** are exclusive: a reading equal to the threshold does not pass. **In range** is exclusive at both bounds. **Outside range** is inclusive: a reading equal to either bound passes. Choose **Number** to enter {{ include.value_short }}, or **Entity** to use a sensor or number helper as a dynamic threshold. +{% if include.has_unit %} +Unit: + description: The {{ include.unit_label }} to use for threshold comparison. Accepts {{ include.unit_options_code }}. Required when using numerical thresholds (not required when using entity references). + default: {{ include.unit_default }} +{% endif %} +Condition passes if: + description: | + When multiple entities are targeted, controls how results combine: + + - **Any**: The condition passes if at least one targeted entity meets the threshold (default). + - **All**: The condition passes only when every targeted entity meets the threshold. +{% endoptions_ui %} diff --git a/source/_includes/conditions/threshold_value_options_yaml.md b/source/_includes/conditions/threshold_value_options_yaml.md new file mode 100644 index 000000000000..a5decfb30b43 --- /dev/null +++ b/source/_includes/conditions/threshold_value_options_yaml.md @@ -0,0 +1,59 @@ +{% comment %} +Reusable "Options in YAML" block for entity conditions that test a reading +against the threshold-mapping schema. The `behavior` description is shared +across the family. Unitless members (humidity, brightness, counter) get the +per-type "Provide value..." guidance; members with a unit (temperature, energy, +etc.) get the unit_of_measurement guidance and a unit-style example instead. + +Parameters: + reading quantity noun, e.g. "humidity", "temperature" + range_note parenthetical range for above/below (unitless), e.g. "0–100" + number_final closing number guidance (unitless), e.g. "a percentage value (0–100)" + has_unit set (to anything) for unit_of_measurement guidance + example + (requires unit_default, unit_example_entity, unit_example_value) + unit_default default unit used in the example, e.g. "°C" + unit_example_entity entity reference used in the example, e.g. + "input_number.comfort_temperature_min" + unit_example_value literal number used in the example, e.g. "22" + threshold_required "true" or "false" for the threshold field (default "false") +{% endcomment %} +{% options_yaml %} +threshold: + description: | + The {{ include.reading }} level the entity has to meet for the condition to pass: + + - `type: above` (exclusive): Sets a minimum. The reading must be strictly above the threshold to pass.{% unless include.has_unit %} Provide `value` with a `number` key ({{ include.range_note }}) or an `entity` key.{% endunless %} + - `type: below` (exclusive): Sets a maximum. The reading must be strictly below the threshold to pass.{% unless include.has_unit %} Provide `value` with a `number` key ({{ include.range_note }}) or an `entity` key.{% endunless %} + - `type: between` (exclusive): Defines a range. The reading must be strictly between both bounds to pass.{% unless include.has_unit %} Provide `value_min` and `value_max`, each with a `number` key or an `entity` key.{% endunless %} + - `type: outside` (inclusive): Defines an outside-range. The reading must be at or beyond either bound to pass.{% unless include.has_unit %} Provide `value_min` and `value_max`, each with a `number` key or an `entity` key.{% endunless %} +{% if include.has_unit %} + + For `type: above` and `type: below`, use `value` with either `number` and `unit_of_measurement`, or `entity`. For `type: between` and `type: outside`, use `value_min` and `value_max`, each with either `number` and `unit_of_measurement`, or `entity`. For example: + + ```yaml + threshold: + type: between + value_min: + entity: {{ include.unit_example_entity }} + value_max: + number: {{ include.unit_example_value }} + unit_of_measurement: {{ include.unit_default }} + ``` + + When using an `entity`, its current reading is used as the threshold at the moment the condition is evaluated, which lets you compare two {{ include.reading }} readings dynamically. +{% else %} + + For the `number` key, use {{ include.number_final }}. For the `entity` key, use an `input_number`, `number`, or `sensor` entity. +{% endif %} + required: {{ include.threshold_required | default: "false" }} + type: map +behavior: + description: | + When multiple entities are targeted, controls how results combine: + + - `any`: The condition passes if at least one targeted entity meets the threshold. + - `all`: The condition passes only when every targeted entity meets the threshold. + required: false + type: string + default: any +{% endoptions_yaml %} diff --git a/source/_includes/conditions/threshold_value_steps.md b/source/_includes/conditions/threshold_value_steps.md new file mode 100644 index 000000000000..40154fe324ab --- /dev/null +++ b/source/_includes/conditions/threshold_value_steps.md @@ -0,0 +1,37 @@ +{% comment %} +Reusable "To use ... in an automation" steps for entity conditions that test a +reading against the threshold-mapping schema (above/below/in range/outside +range). Used by humidity.is_value; reusable by climate.target_humidity, +light.is_brightness, counter.is_value, and similar. + +Parameters: + title UI display name, e.g. "Relative humidity" + sensor sensor noun, e.g. "humidity sensor" + areas example areas, e.g. "bedroom or bathroom" + reading quantity noun, e.g. "humidity" + value_long Number-entry phrasing, e.g. "a fixed percentage directly, for example `65` for 65%" + has_unit set (to anything) to add a "Unit" step (requires unit_label, unit_options) + unit_label unit-kind label, e.g. "temperature unit", "energy unit" + unit_options bare list of allowed units for prose, e.g. "°C or °F" +{% endcomment %} +To use **{{ include.title }}** in an automation: + +1. Go to {% my automations title="**Settings** > **Automations & scenes**" %}. +2. Open an existing automation, or select **Create automation** > **Create new automation**. +3. In the **And if** section, select **Add condition**. +4. Select what you want to check. Under **By target** (see [Targets](#targets)), pick the area your {{ include.sensor }} is in (like your {{ include.areas }}). You can also select a device, a specific entity, or a label. +5. From the conditions shown for that target, select **{{ include.title }}**. +6. Under **Threshold type**, set the {{ include.reading }} level the condition checks against: + 1. Pick whether the reading must be **Above**, **Below**, **In range**, or **Outside range** of the threshold. + 2. Select **Number** or **Entity**: + - **Number**: Enter {{ include.value_long }}. For **In range** or **Outside range**, enter both a lower and upper bound. + - **Entity**: Use a sensor entity or a [number helper](/integrations/input_number/) entity as the threshold: + - Number helper: You can adjust the threshold value without editing the automation. The sensor reading is compared against the number helper's current value. + - Sensor: Its current reading becomes the threshold and updates automatically as the sensor changes. This is useful for comparing two {{ include.reading }} readings, for example to check whether indoor {{ include.reading }} is higher than outdoor {{ include.reading }}. + - For **In range** or **Outside range**, you need two entities: one for the lower bound and one for the upper bound (for example, two separate number helpers). + - If you don't have a number helper, you can create one by selecting **Create a new number helper**. +{%- if include.has_unit %} +7. Under **Unit**, select the {{ include.unit_label }} ({{ include.unit_options }}) to use for the threshold comparison. +{%- endif %} +8. Under **Condition passes if** (see [Behavior](#behavior-with-multiple-targets)), pick **Any** or **All**. +9. Select **Save**. diff --git a/source/_includes/triggers/threshold_changed_options_ui.md b/source/_includes/triggers/threshold_changed_options_ui.md new file mode 100644 index 000000000000..df39b9e835e1 --- /dev/null +++ b/source/_includes/triggers/threshold_changed_options_ui.md @@ -0,0 +1,28 @@ +{% comment %} +Reusable "Options in the UI" block for "changed" entity triggers that use the +threshold-mapping schema. + +Parameters: + unit_phrase_ui value-entry phrasing, e.g. "a fixed percentage (0–100%)" + has_unit set (to anything) to add a "Unit" row (requires unit_label, + unit_options_code, unit_default) + unit_label unit-kind label, e.g. "temperature unit", "energy unit" + unit_options_code inline-code list of allowed units, e.g. "`°C` or `°F`" + unit_default default unit, e.g. "°C" +{% endcomment %} +{% options_ui %} +Threshold type: + description: | + Controls which changes fire the trigger: + + - **Any change**: fires on any change, regardless of direction or new value. + - **Above** or **Below** (exclusive): fires only when the new reading is strictly above or below the threshold. A reading equal to the threshold does not fire the trigger. + - **In range** (exclusive): fires only when the new reading is strictly between the two bounds. A reading equal to either bound does not fire the trigger. + - **Outside range** (inclusive): fires when the new reading is at or below the lower bound, or at or above the upper bound. A reading equal to either bound fires the trigger. + + For each mode you can enter {{ include.unit_phrase_ui }} or reference a sensor entity or a [number helper](/integrations/input_number/) entity. +{% if include.has_unit %} +Unit: + description: The {{ include.unit_label }} to use for threshold comparison. Accepts {{ include.unit_options_code }}. Required when using numerical thresholds (not required when using entity references). Default is `{{ include.unit_default }}`. +{% endif %} +{% endoptions_ui %} diff --git a/source/_includes/triggers/threshold_changed_options_yaml.md b/source/_includes/triggers/threshold_changed_options_yaml.md new file mode 100644 index 000000000000..f2e12af4009f --- /dev/null +++ b/source/_includes/triggers/threshold_changed_options_yaml.md @@ -0,0 +1,48 @@ +{% comment %} +Reusable "Options in YAML" block for "changed" entity triggers that use the +threshold-mapping schema. + +Parameters: + reading quantity noun, e.g. "humidity", "temperature" + unit_phrase_yaml literal-value phrasing, e.g. "literal percentage 0–100" + has_unit set (to anything) to add unit_of_measurement guidance + example + (requires unit_label, unit_options_code, unit_default, + unit_example_entity, unit_example_value) + unit_label unit-kind label, e.g. "temperature unit", "energy unit" + unit_options_code inline-code list of allowed units, e.g. "`°C` or `°F`" + unit_default default unit used in the example, e.g. "°C" + unit_example_entity entity reference used in the example, e.g. + "input_number.comfort_temperature_min" + unit_example_value literal number used in the example, e.g. "24" +{% endcomment %} +{% options_yaml %} +threshold: + description: | + A mapping that defines which kind of change fires the trigger: + + - `type: any`: Fires on any {{ include.reading }} change (no additional keys needed). + - `type: above` (exclusive): Sets a minimum. Fires when the reading is strictly above `value`. A reading equal to `value` does not fire the trigger. Provide `value` with a `number` key (for a {{ include.unit_phrase_yaml }}) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). + - `type: below` (exclusive): Sets a maximum. Fires when the reading is strictly below `value`. A reading equal to `value` does not fire the trigger. Provide `value` with a `number` key (for a {{ include.unit_phrase_yaml }}) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). + - `type: between` (exclusive): Defines a range. Fires when the reading is strictly between `value_min` and `value_max`. Readings equal to either bound do not fire the trigger. Provide `value_min` and `value_max`, each with a `number` key (for a {{ include.unit_phrase_yaml }}) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). + - `type: outside` (inclusive): Defines an outside-range. Fires when the reading is at or below `value_min`, or at or above `value_max`. Readings equal to either bound fire the trigger. Provide `value_min` and `value_max`, each with a `number` key (for a {{ include.unit_phrase_yaml }}) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). +{% if include.has_unit %} + + When using the `number` key, you must also include `unit_of_measurement` to specify the {{ include.unit_label }} ({{ include.unit_options_code }}). When using the `entity` key, the unit is taken from the entity itself, or assumed to be the system {{ include.unit_label }} if the entity has no unit. + + For example: + + ```yaml + threshold: + type: outside + value_min: + entity: {{ include.unit_example_entity }} + value_max: + number: {{ include.unit_example_value }} + unit_of_measurement: {{ include.unit_default }} + ``` + + A `sensor` or `number` entity's current value is used as the threshold, which lets you compare two {{ include.reading }} readings dynamically. +{% endif %} + required: true + type: map +{% endoptions_yaml %} diff --git a/source/_includes/triggers/threshold_changed_steps.md b/source/_includes/triggers/threshold_changed_steps.md new file mode 100644 index 000000000000..bd20edb2a315 --- /dev/null +++ b/source/_includes/triggers/threshold_changed_steps.md @@ -0,0 +1,33 @@ +{% comment %} +Reusable "To use ... in an automation" steps for entity triggers that use the +threshold-mapping schema (type: any/above/below/between/outside) and fire on a +"changed" event. Used by humidity.changed; reusable by climate.target_humidity_changed, +light.brightness_changed, battery.level_changed, and similar. + +Parameters: + title UI display name, e.g. "Relative humidity changed" + sensor sensor noun, e.g. "humidity sensor" + areas example areas, e.g. "bathroom or bedroom" + unit_phrase_ui value-entry phrasing, e.g. "a fixed percentage (0–100%)" + has_unit set (to anything) to add a "Unit" step (requires unit_label, unit_options) + unit_label unit-kind label, e.g. "temperature unit", "energy unit" + unit_options bare list of allowed units for prose, e.g. "°C or °F" +{% endcomment %} +To use **{{ include.title }}** in an automation: + +1. Go to {% my automations title="**Settings** > **Automations & scenes**" %}. +2. Open an existing automation, or select **Create automation** > **Create new automation**. +3. In the **When** section, select **Add trigger**. +4. Select what you want to monitor. Under **By target** (see [Targets](#targets)), pick the area your {{ include.sensor }} is in (like your {{ include.areas }}). You can also select a device, a specific entity, or a label. When you target multiple entities (via area, label, or multiple entity selections), the trigger fires whenever any of them changes. +5. From the triggers shown for that target, select **{{ include.title }}**. +6. Under **Threshold type**, configure what kind of change fires the trigger: + - Select **Any change** to fire on any change, regardless of direction or new value. + - Select **Above** or **Below** and enter a value to fire only when the new reading is above or below that value. + - Select **In range** and enter a lower and upper bound to fire only when the new reading falls inside the range. + - Select **Outside range** and enter a lower and upper bound to fire only when the new reading is outside the range. + - For each option, you can enter {{ include.unit_phrase_ui }}, pick a sensor entity or a [number helper](/integrations/input_number/) entity as the threshold. + - If you don't have a number helper, you can create one by selecting **Create a new number helper**. +{%- if include.has_unit %} +7. Under **Unit**, select the {{ include.unit_label }} ({{ include.unit_options }}) to use for the threshold comparison. +{%- endif %} +8. Select **Save**. diff --git a/source/_includes/triggers/threshold_crossed_options_ui.md b/source/_includes/triggers/threshold_crossed_options_ui.md new file mode 100644 index 000000000000..9f59edfa0f72 --- /dev/null +++ b/source/_includes/triggers/threshold_crossed_options_ui.md @@ -0,0 +1,39 @@ +{% comment %} +Reusable "Options in the UI" block for "crossed threshold" entity triggers that +use the threshold-mapping schema. + +Parameters: + unit_phrase_ui value-entry phrasing, e.g. "a fixed percentage (0–100%)" + has_unit set (to anything) to add a "Unit" row (requires unit_label, + unit_options_code, unit_default) + unit_label unit-kind label, e.g. "temperature unit", "energy unit" + unit_options_code inline-code list of allowed units, e.g. "`°C` or `°F`" + unit_default default unit, e.g. "°C" +{% endcomment %} +{% options_ui %} +Threshold type: + description: | + Controls which threshold crossings fire the trigger: + + - **Above** (exclusive): fires when the reading crosses to strictly above the threshold. A reading equal to the threshold does not trigger a crossing. + - **Below** (exclusive): fires when the reading crosses to strictly below the threshold. A reading equal to the threshold does not trigger a crossing. + - **In range** (exclusive): fires when the reading crosses into the range. A reading equal to either bound is not considered inside the range. + - **Outside range** (inclusive): fires when the reading crosses out of the range. A reading equal to either bound is considered outside the range. + + For each mode you can enter {{ include.unit_phrase_ui }} or reference a sensor entity or a [number helper](/integrations/input_number/) entity. +{% if include.has_unit %} +Unit: + description: The {{ include.unit_label }} to use for threshold comparison. Accepts {{ include.unit_options_code }}. Required when using numerical thresholds (not required when using entity references). Default is `{{ include.unit_default }}`. +{% endif %} +Trigger when: + description: | + When multiple entities are targeted, controls when the trigger fires: + + - **Each**: fires every time any targeted entity crosses the threshold. + - **First**: fires only on the first crossing. + - **All**: fires only after every targeted entity crosses the threshold. + + This corresponds to the `behavior` field in YAML. Default is **Each**. +For at least: + description: How long the reading must remain past the threshold before the trigger fires. Useful to avoid triggering on brief fluctuations. For example, set it to `0:05:00` to fire only after the reading has stayed past the threshold for 5 minutes. Default is `0` (fires immediately). +{% endoptions_ui %} diff --git a/source/_includes/triggers/threshold_crossed_options_yaml.md b/source/_includes/triggers/threshold_crossed_options_yaml.md new file mode 100644 index 000000000000..1b9b4547e6d0 --- /dev/null +++ b/source/_includes/triggers/threshold_crossed_options_yaml.md @@ -0,0 +1,78 @@ +{% comment %} +Reusable "Options in YAML" block for "crossed threshold" entity triggers that +use the threshold-mapping schema. The `behavior` and `for` field descriptions +are identical across the whole family. Suited to unitless members (humidity, +brightness, battery); members with a unit (temperature, energy, etc.) get an +added unit_of_measurement note in the threshold description. + +Parameters: + reading quantity noun, e.g. "humidity", "temperature" + unit_phrase_yaml literal-value phrasing, e.g. "literal percentage 0–100" + example_value value used in the inline example (unitless members), e.g. "70" + has_unit set (to anything) for unit_of_measurement note + a unit-style + example (requires unit_label, unit_options_code, unit_default, + unit_example_entity, unit_example_value) + unit_label unit-kind label, e.g. "temperature unit", "energy unit" + unit_options_code inline-code list of allowed units, e.g. "`°C` or `°F`" + unit_default default unit used in the example, e.g. "°C" + unit_example_entity entity reference used in the example, e.g. + "input_number.max_comfort_temperature" + unit_example_value literal number used in the example, e.g. "18" +{% endcomment %} +{% options_yaml %} +threshold: + description: | + A mapping that defines the threshold crossing that fires the trigger: + + - `type: above` (exclusive): Sets a minimum. Fires when the reading crosses to strictly above `value`. A reading equal to `value` does not trigger a crossing. Provide `value` with a `number` key (for a {{ include.unit_phrase_yaml }}) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). + - `type: below` (exclusive): Sets a maximum. Fires when the reading crosses to strictly below `value`. A reading equal to `value` does not trigger a crossing. Provide `value` with a `number` key (for a {{ include.unit_phrase_yaml }}) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). + - `type: between` (exclusive): Defines a range. Fires when the reading crosses into the range. A reading equal to either bound is not inside the range. Provide `value_min` and `value_max`, each with a `number` key (for a {{ include.unit_phrase_yaml }}) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). + - `type: outside` (inclusive): Defines an outside-range. Fires when the reading crosses out of the range. A reading equal to either bound is outside the range. Provide `value_min` and `value_max`, each with a `number` key (for a {{ include.unit_phrase_yaml }}) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). + +{% if include.has_unit %} + + When using the `number` key, you must also include `unit_of_measurement` to specify the {{ include.unit_label }} ({{ include.unit_options_code }}). When using the `entity` key, the unit is taken from the entity itself, or assumed to be the system {{ include.unit_label }} if the entity has no unit. + + For example: + + ```yaml + threshold: + type: between + value_min: + number: {{ include.unit_example_value }} + unit_of_measurement: {{ include.unit_default }} + value_max: + entity: {{ include.unit_example_entity }} + ``` + + A `sensor` or `number` entity's current value is used as the threshold, which lets you compare two {{ include.reading }} readings dynamically. +{% else %} + + For example: + + ```yaml + threshold: + type: above + value: + number: {{ include.example_value }} + ``` +{% endif %} + required: true + type: map +behavior: + description: | + When multiple entities are targeted, controls when the trigger fires: + + - `any` (**Each** in the UI, default): fires every time any targeted entity crosses the threshold. + - `first` (**First** in the UI): fires only on the first threshold crossing. + - `last` (**All** in the UI): fires only after every targeted entity crosses the threshold. + required: false + type: string + default: any +for: + description: | + How long the reading must remain past the threshold before the trigger fires. Accepts a duration string in `HH:MM:SS` format. For example, `00:05:00` fires only after the reading has stayed past the threshold for 5 minutes. + required: false + type: string + default: "00:00:00" +{% endoptions_yaml %} diff --git a/source/_includes/triggers/threshold_crossed_steps.md b/source/_includes/triggers/threshold_crossed_steps.md new file mode 100644 index 000000000000..3c38de521df2 --- /dev/null +++ b/source/_includes/triggers/threshold_crossed_steps.md @@ -0,0 +1,34 @@ +{% comment %} +Reusable "To use ... in an automation" steps for entity triggers that use the +threshold-mapping schema and fire when a reading crosses a threshold. Used by +humidity.crossed_threshold; reusable by climate.target_humidity_crossed_threshold, +light.brightness_crossed_threshold, battery.level_crossed, and similar. + +Parameters: + title UI display name, e.g. "Relative humidity crossed threshold" + sensor sensor noun, e.g. "humidity sensor" + areas example areas, e.g. "bathroom or basement" + unit_phrase_ui value-entry phrasing, e.g. "a fixed percentage (0–100%)" + has_unit set (to anything) to add a "Unit" step (requires unit_label, unit_options) + unit_label unit-kind label, e.g. "temperature unit", "energy unit" + unit_options bare list of allowed units for prose, e.g. "°C or °F" +{% endcomment %} +To use **{{ include.title }}** in an automation: + +1. Go to {% my automations title="**Settings** > **Automations & scenes**" %}. +2. Open an existing automation, or select **Create automation** > **Create new automation**. +3. In the **When** section, select **Add trigger**. +4. Select what you want to monitor. Under **By target** (see [Targets](#targets)), pick the area your {{ include.sensor }} is in (like your {{ include.areas }}). You can also select a device, a specific entity, or a label. +5. From the triggers shown for that target, select **{{ include.title }}**. +6. Under **Threshold type**, configure the zone the reading must enter for the trigger to fire: + - Select **Above** or **Below** and enter a value to fire when the reading crosses that level. + - Select **In range** and enter a lower and upper bound to fire when the reading enters the range from outside. + - Select **Outside range** and enter a lower and upper bound to fire when the reading leaves the range (crosses past either bound). + - For each option, you can enter {{ include.unit_phrase_ui }}, pick a sensor entity or a [number helper](/integrations/input_number/) entity as the threshold. + - If you don't have a number helper, you can create one by selecting **Create a new number helper**. +{%- if include.has_unit %} +7. Under **Unit**, select the {{ include.unit_label }} ({{ include.unit_options }}) to use for the threshold comparison. +{%- endif %} +8. Under **Trigger when** (see [Behavior](#behavior-with-multiple-targets)), pick **Each**, **First**, or **All** to control how the trigger behaves when multiple entities are targeted. +9. Under **For at least**, set how long the reading must stay past the threshold before the trigger fires. Leave it at zero to fire immediately. +10. Select **Save**. diff --git a/source/_triggers/humidity.changed.markdown b/source/_triggers/humidity.changed.markdown index 9857ca2d2ef4..834d0cdb6b84 100644 --- a/source/_triggers/humidity.changed.markdown +++ b/source/_triggers/humidity.changed.markdown @@ -17,36 +17,16 @@ Use **Relative humidity changed** to log humidity trends, trigger a fan when the {% include triggers/ui_header.md %} -To use **Relative humidity changed** in an automation: - -1. Go to {% my automations title="**Settings** > **Automations & scenes**" %}. -2. Open an existing automation, or select **Create automation** > **Create new automation**. -3. In the **When** section, select **Add trigger**. -4. Select what you want to monitor. Under **By target** (see [Targets](#targets)), pick the area your humidity sensor is in (like your bathroom or bedroom). You can also select a device, a specific entity, or a label. When you target multiple entities (via area, label, or multiple entity selections), the trigger fires whenever any of them changes. -5. From the triggers shown for that target, select **Relative humidity changed**. -6. Under **Threshold type**, configure what kind of change fires the trigger: - - Select **Any change** to fire on any change, regardless of direction or new value. - - Select **Above** or **Below** and enter a value to fire only when the new reading is above or below that value. - - Select **In range** and enter a lower and upper bound to fire only when the new reading falls inside the range. - - Select **Outside range** and enter a lower and upper bound to fire only when the new reading is outside the range. - - For each option, you can enter a fixed percentage (0-100%), pick a sensor entity or a [number helper](/integrations/input_number/) entity as the threshold. - - If you don't have a number helper, you can create one by selecting **Create a new number helper**. -7. Select **Save**. +{% include triggers/threshold_changed_steps.md + title="Relative humidity changed" + sensor="humidity sensor" + areas="bathroom or bedroom" + unit_phrase_ui="a fixed percentage (0–100%)" %} ### Options in the UI -{% options_ui %} -Threshold type: - description: | - Controls which changes fire the trigger: - - - **Any change**: fires on any change, regardless of direction or new value. - - **Above** or **Below** (exclusive): fires only when the new reading is strictly above or below the threshold. A reading equal to the threshold does not fire the trigger. - - **In range** (exclusive): fires only when the new reading is strictly between the two bounds. A reading equal to either bound does not fire the trigger. - - **Outside range** (inclusive): fires when the new reading is at or below the lower bound, or at or above the upper bound. A reading equal to either bound fires the trigger. - - For each mode you can enter a fixed percentage (0–100%) or reference a sensor entity or a [number helper](/integrations/input_number/) entity. -{% endoptions_ui %} +{% include triggers/threshold_changed_options_ui.md + unit_phrase_ui="a fixed percentage (0–100%)" %} {% include triggers/yaml_header.md %} @@ -138,19 +118,9 @@ This fires whenever any humidity sensor in the basement area changes to a value YAML sometimes provides additional options for more complex use cases that are not available through the UI. -{% options_yaml %} -threshold: - description: | - A mapping that defines which kind of change fires the trigger: - - - `type: any`: Fires on any humidity change (no additional keys needed). - - `type: above` (exclusive): Sets a minimum. Fires when the reading is strictly above `value`. A reading equal to `value` does not fire the trigger. Provide `value` with a `number` key (for a literal percentage 0–100) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). - - `type: below` (exclusive): Sets a maximum. Fires when the reading is strictly below `value`. A reading equal to `value` does not fire the trigger. Provide `value` with a `number` key (for a literal percentage 0–100) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). - - `type: between` (exclusive): Defines a range. Fires when the reading is strictly between `value_min` and `value_max`. Readings equal to either bound do not fire the trigger. Provide `value_min` and `value_max`, each with a `number` key (for a literal percentage 0–100) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). - - `type: outside` (inclusive): Defines an outside-range. Fires when the reading is at or below `value_min`, or at or above `value_max`. Readings equal to either bound fire the trigger. Provide `value_min` and `value_max`, each with a `number` key (for a literal percentage 0–100) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). - required: true - type: map -{% endoptions_yaml %} +{% include triggers/threshold_changed_options_yaml.md + reading="humidity" + unit_phrase_yaml="literal percentage 0–100" %} {% include triggers/targets.md %} diff --git a/source/_triggers/humidity.crossed_threshold.markdown b/source/_triggers/humidity.crossed_threshold.markdown index b3147a5fa7d1..acdfde4a47c5 100644 --- a/source/_triggers/humidity.crossed_threshold.markdown +++ b/source/_triggers/humidity.crossed_threshold.markdown @@ -17,47 +17,16 @@ When you target more than one entity, the trigger's **Trigger when** option cont {% include triggers/ui_header.md %} -To use **Relative humidity crossed threshold** in an automation: - -1. Go to {% my automations title="**Settings** > **Automations & scenes**" %}. -2. Open an existing automation, or select **Create automation** > **Create new automation**. -3. In the **When** section, select **Add trigger**. -4. Select what you want to monitor. Under **By target** (see [Targets](#targets)), pick the area your humidity sensor is in (like your bathroom or basement). You can also select a device, a specific entity, or a label. -5. From the triggers shown for that target, select **Relative humidity crossed threshold**. -6. Under **Threshold type**, configure the zone the reading must enter for the trigger to fire: - - Select **Above** or **Below** and enter a value to fire when the reading crosses that level. - - Select **In range** and enter a lower and upper bound to fire when the reading enters the range from outside. - - Select **Outside range** and enter a lower and upper bound to fire when the reading leaves the range (crosses past either bound). -For each option, you can enter a fixed percentage (0-100%), pick a sensor entity or a [number helper](/integrations/input_number/) entity as the threshold. If you don't have a number helper, you can create one by selecting **Create a new number helper**. -7. Under **Trigger when** (see [Behavior](#behavior-with-multiple-targets)), pick **Each**, **First**, or **All** to control how the trigger behaves when multiple entities are targeted. -8. Under **For at least**, set how long the reading must stay past the threshold before the trigger fires. Leave it at zero to fire immediately. -9. Select **Save**. +{% include triggers/threshold_crossed_steps.md + title="Relative humidity crossed threshold" + sensor="humidity sensor" + areas="bathroom or basement" + unit_phrase_ui="a fixed percentage (0–100%)" %} ### Options in the UI -{% options_ui %} -Threshold type: - description: | - Controls which threshold crossings fire the trigger: - - - **Above** (exclusive): fires when the reading crosses to strictly above the threshold. A reading equal to the threshold does not trigger a crossing. - - **Below** (exclusive): fires when the reading crosses to strictly below the threshold. A reading equal to the threshold does not trigger a crossing. - - **In range** (exclusive): fires when the reading crosses into the range. A reading equal to either bound is not considered inside the range. - - **Outside range** (inclusive): fires when the reading crosses out of the range. A reading equal to either bound is considered outside the range. - - For each mode you can enter a fixed percentage (0–100%) or reference a sensor entity or a [number helper](/integrations/input_number/) entity. -Trigger when: - description: | - When multiple entities are targeted, controls when the trigger fires: - - - **Each**: fires every time any targeted entity crosses the threshold. - - **First**: fires only on the first crossing. - - **All**: fires only after every targeted entity crosses the threshold. - - This corresponds to the `behavior` field in YAML. Default is **Each**. -For at least: - description: How long the reading must remain past the threshold before the trigger fires. Useful to avoid triggering on brief fluctuations. For example, set it to `0:05:00` to fire only after the reading has stayed past the threshold for 5 minutes. Default is `0` (fires immediately). -{% endoptions_ui %} +{% include triggers/threshold_crossed_options_ui.md + unit_phrase_ui="a fixed percentage (0–100%)" %} {% include triggers/yaml_header.md %} @@ -121,43 +90,9 @@ This fires when the first humidity sensor with the `humidity_sensors` label cros YAML sometimes provides additional options for more complex use cases that are not available through the UI. -{% options_yaml %} -threshold: - description: | - A mapping that defines the threshold crossing that fires the trigger: - - - `type: above` (exclusive): Sets a minimum. Fires when the reading crosses to strictly above `value`. A reading equal to `value` does not trigger a crossing. Provide `value` with a `number` key (for a literal percentage 0–100) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). - - `type: below` (exclusive): Sets a maximum. Fires when the reading crosses to strictly below `value`. A reading equal to `value` does not trigger a crossing. Provide `value` with a `number` key (for a literal percentage 0–100) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). - - `type: between` (exclusive): Defines a range. Fires when the reading crosses into the range. A reading equal to either bound is not inside the range. Provide `value_min` and `value_max`, each with a `number` key (for a literal percentage 0–100) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). - - `type: outside` (inclusive): Defines an outside-range. Fires when the reading crosses out of the range. A reading equal to either bound is outside the range. Provide `value_min` and `value_max`, each with a `number` key (for a literal percentage 0–100) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). - - For example: - - ```yaml - threshold: - type: above - value: - number: 70 - ``` - required: true - type: map -behavior: - description: | - When multiple entities are targeted, controls when the trigger fires: - - - `any` (**Each** in the UI, default): fires every time any targeted entity crosses the threshold. - - `first` (**First** in the UI): fires only on the first threshold crossing. - - `last` (**All** in the UI): fires only after every targeted entity crosses the threshold. - required: false - type: string - default: any -for: - description: | - How long the reading must remain past the threshold before the trigger fires. Accepts a duration string in `HH:MM:SS` format. For example, `00:05:00` fires only after the reading has stayed past the threshold for 5 minutes. - required: false - type: string - default: "00:00:00" -{% endoptions_yaml %} +{% include triggers/threshold_crossed_options_yaml.md + unit_phrase_yaml="literal percentage 0–100" + example_value="70" %} {% include triggers/targets.md %} diff --git a/source/_triggers/temperature.changed.markdown b/source/_triggers/temperature.changed.markdown index 996738a0226c..65e7cad89e59 100644 --- a/source/_triggers/temperature.changed.markdown +++ b/source/_triggers/temperature.changed.markdown @@ -15,39 +15,23 @@ Use **Temperature changed** to log temperature trends, trigger heating or coolin {% include triggers/ui_header.md %} -To use **Temperature changed** in an automation: - -1. Go to {% my automations title="**Settings** > **Automations & scenes**" %}. -2. Open an existing automation, or select **Create automation** > **Create new automation**. -3. In the **When** section, select **Add trigger**. -4. Select what you want to monitor. Under **By target** (see [Targets](#targets)), pick the area your temperature sensor is in (like your bedroom or living room). You can also select a device, a specific entity, or a label. -5. From the triggers shown for that target, select **Temperature changed**. -6. Under **Threshold type**, configure what kind of change fires the trigger: - - Select **Any change** to fire on any change, regardless of direction or new value. - - Select **Above** or **Below** and enter a value to fire only when the new reading is above or below that value. - - Select **In range** and enter a lower and upper bound to fire only when the new reading falls inside the range. - - Select **Outside range** and enter a lower and upper bound to fire only when the new reading is outside the range. - - For each option, you can enter a fixed temperature, pick a sensor entity or a [number helper](/integrations/input_number/) entity as the threshold. - - If you don't have a number helper, you can create one by selecting **Create a new number helper**. -7. Under **Unit**, select the temperature unit (°C or °F) to use for the threshold comparison. -8. Select **Save**. +{% include triggers/threshold_changed_steps.md + title="Temperature changed" + sensor="temperature sensor" + areas="bedroom or living room" + unit_phrase_ui="a fixed temperature" + has_unit="true" + unit_label="temperature unit" + unit_options="°C or °F" %} ### Options in the UI -{% options_ui %} -Threshold type: - description: | - Controls which changes fire the trigger: - - - **Any change**: fires on any change, regardless of direction or new value. - - **Above** or **Below** (exclusive): fires only when the new reading is strictly above or below the threshold. A reading equal to the threshold does not fire the trigger. - - **In range** (exclusive): fires only when the new reading is strictly between the two bounds. A reading equal to either bound does not fire the trigger. - - **Outside range** (inclusive): fires when the new reading is at or below the lower bound, or at or above the upper bound. A reading equal to either bound fires the trigger. - - For each mode you can enter a fixed temperature or reference a sensor entity or a [number helper](/integrations/input_number/) entity. -Unit: - description: The temperature unit to use for threshold comparison. Accepts `°C` or `°F`. Required when using numerical thresholds (not required when using entity references). Default is `°C`. -{% endoptions_ui %} +{% include triggers/threshold_changed_options_ui.md + unit_phrase_ui="a fixed temperature" + has_unit="true" + unit_label="temperature unit" + unit_options_code="`°C` or `°F`" + unit_default="°C" %} {% include triggers/yaml_header.md %} @@ -108,35 +92,15 @@ trigger: | YAML sometimes provides additional options for more complex use cases that are not available through the UI. -{% options_yaml %} -threshold: - description: | - A mapping that defines which kind of change fires the trigger: - - - `type: any`: Fires on any temperature change (no additional keys needed). - - `type: above` (exclusive): Sets a minimum. Fires when the reading is strictly above `value`. A reading equal to `value` does not fire the trigger. Provide `value` with a `number` key (for a literal number) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). - - `type: below` (exclusive): Sets a maximum. Fires when the reading is strictly below `value`. A reading equal to `value` does not fire the trigger. Provide `value` with a `number` key (for a literal number) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). - - `type: between` (exclusive): Defines a range. Fires when the reading is strictly between `value_min` and `value_max`. Readings equal to either bound do not fire the trigger. Provide `value_min` and `value_max`, each with a `number` key (for a literal number) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). - - `type: outside` (inclusive): Defines an outside-range. Fires when the reading is at or below `value_min`, or at or above `value_max`. Readings equal to either bound fire the trigger. Provide `value_min` and `value_max`, each with a `number` key (for a literal number) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). - - When using the `number` key, you must also include `unit_of_measurement` to specify the temperature unit (`°C` or `°F`). When using the `entity` key, the unit is taken from the entity itself, or assumed to be the system temperature unit if the entity has no unit. - - For example: - - ```yaml - threshold: - type: outside - value_min: - entity: input_number.comfort_temperature_min - value_max: - number: 24 - unit_of_measurement: °C - ``` - - A `sensor` or `number` entity's current value is used as the threshold, which lets you compare two temperature readings dynamically. - required: true - type: map -{% endoptions_yaml %} +{% include triggers/threshold_changed_options_yaml.md + reading="temperature" + unit_phrase_yaml="literal number" + has_unit="true" + unit_label="temperature unit" + unit_options_code="`°C` or `°F`" + unit_default="°C" + unit_example_entity="input_number.comfort_temperature_min" + unit_example_value="24" %} {% include triggers/targets.md %} diff --git a/source/_triggers/temperature.crossed_threshold.markdown b/source/_triggers/temperature.crossed_threshold.markdown index 333c822065d6..feb9f0bc35d3 100644 --- a/source/_triggers/temperature.crossed_threshold.markdown +++ b/source/_triggers/temperature.crossed_threshold.markdown @@ -17,51 +17,23 @@ When you target more than one entity, the trigger's **Trigger when** option cont {% include triggers/ui_header.md %} -To use **Temperature crossed threshold** in an automation: - -1. Go to {% my automations title="**Settings** > **Automations & scenes**" %}. -2. Open an existing automation, or select **Create automation** > **Create new automation**. -3. In the **When** section, select **Add trigger**. -4. Select what you want to monitor. Under **By target** (see [Targets](#targets)), pick the area your temperature sensor is in (like your bedroom or living room). You can also select a device, a specific entity, or a label. -5. From the triggers shown for that target, select **Temperature crossed threshold**. -6. Under **Threshold type**, configure the zone the reading must enter for the trigger to fire: - - Select **Above** or **Below** and enter a value to fire when the reading crosses that level. - - Select **In range** and enter a lower and upper bound to fire when the reading enters the range from outside. - - Select **Outside range** and enter a lower and upper bound to fire when the reading leaves the range (crosses past either bound). - - For each option, you can enter a fixed temperature or pick a sensor entity or a [number helper](/integrations/input_number/) entity as the threshold. - - If you don't have a number helper, you can create one by selecting **Create a new number helper**. -7. Under **Unit**, select the temperature unit (°C or °F) to use for the threshold comparison. -8. Under **Trigger when** (see [Behavior](#behavior-with-multiple-targets)), pick **Each**, **First**, or **All** to control how the trigger behaves when multiple entities are targeted. -9. Under **For at least**, set how long the reading must stay past the threshold before the trigger fires. Leave it at zero to fire immediately. -10. Select **Save**. +{% include triggers/threshold_crossed_steps.md + title="Temperature crossed threshold" + sensor="temperature sensor" + areas="bedroom or living room" + unit_phrase_ui="a fixed temperature" + has_unit="true" + unit_label="temperature unit" + unit_options="°C or °F" %} ### Options in the UI -{% options_ui %} -Threshold type: - description: | - Controls which threshold crossings fire the trigger: - - - **Above** (exclusive): fires when the reading crosses to strictly above the threshold. A reading equal to the threshold does not trigger a crossing. - - **Below** (exclusive): fires when the reading crosses to strictly below the threshold. A reading equal to the threshold does not trigger a crossing. - - **In range** (exclusive): fires when the reading crosses into the range. A reading equal to either bound is not considered inside the range. - - **Outside range** (inclusive): fires when the reading crosses out of the range. A reading equal to either bound is considered outside the range. - - For each mode you can enter a fixed temperature or reference a sensor entity or [number helper](/integrations/input_number/) entity. -Unit: - description: The temperature unit to use for threshold comparison. Accepts `°C` or `°F`. Required when using numerical thresholds (not required when using entity references). Default is `°C`. -Trigger when: - description: | - When multiple entities are targeted, controls when the trigger fires: - - - **Each**: fires every time any targeted entity crosses the threshold. - - **First**: fires only on the first crossing. - - **All**: fires only after every targeted entity crosses the threshold. - - This corresponds to the `behavior` field in YAML. Default is **Each**. -For at least: - description: How long the reading must remain past the threshold before the trigger fires. Useful to avoid triggering on brief fluctuations. For example, set it to `0:05:00` to fire only after the reading has stayed past the threshold for 5 minutes. Default is `0` (fires immediately). -{% endoptions_ui %} +{% include triggers/threshold_crossed_options_ui.md + unit_phrase_ui="a fixed temperature" + has_unit="true" + unit_label="temperature unit" + unit_options_code="`°C` or `°F`" + unit_default="°C" %} {% include triggers/yaml_header.md %} @@ -107,50 +79,15 @@ trigger: | YAML sometimes provides additional options for more complex use cases that are not available through the UI. -{% options_yaml %} -threshold: - description: | - A mapping that defines the zone the reading must enter for the trigger to fire: - - - `type: above` (exclusive): Sets a minimum. Fires when the reading crosses to strictly above `value`. A reading equal to `value` does not trigger a crossing. Provide `value` with a `number` key (for a literal number) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). - - `type: below` (exclusive): Sets a maximum. Fires when the reading crosses to strictly below `value`. A reading equal to `value` does not trigger a crossing. Provide `value` with a `number` key (for a literal number) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). - - `type: between` (exclusive): Defines a range. Fires when the reading crosses into the range. A reading equal to either bound is not inside the range. Provide `value_min` and `value_max`, each with a `number` key (for a literal number) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). - - `type: outside` (inclusive): Defines an outside-range. Fires when the reading crosses out of the range. A reading equal to either bound is outside the range. Provide `value_min` and `value_max`, each with a `number` key (for a literal number) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). - - When using the `number` key, you must also include `unit_of_measurement` to specify the temperature unit (`°C` or `°F`). When using the `entity` key, the unit is taken from the entity itself, or assumed to be the system temperature unit if the entity has no unit. - - For example: - - ```yaml - threshold: - type: between - value_min: - number: 18 - unit_of_measurement: °C - value_max: - entity: input_number.max_comfort_temperature - ``` - - A `sensor` or `number` entity's current value is used as the threshold, which lets you compare two temperature readings dynamically. - required: true - type: map -behavior: - description: | - When multiple entities are targeted, controls when the trigger fires: - - - `any` (**Each** in the UI, default): fires every time any targeted entity crosses the threshold. - - `first` (**First** in the UI): fires only on the first threshold crossing. - - `last` (**All** in the UI): fires only after every targeted entity crosses the threshold. - required: false - type: string - default: any -for: - description: | - How long the reading must remain past the threshold before the trigger fires. Accepts a duration string in `HH:MM:SS` format. For example, `00:05:00` fires only after the reading has stayed past the threshold for 5 minutes. - required: false - type: string - default: "00:00:00" -{% endoptions_yaml %} +{% include triggers/threshold_crossed_options_yaml.md + reading="temperature" + unit_phrase_yaml="literal number" + has_unit="true" + unit_label="temperature unit" + unit_options_code="`°C` or `°F`" + unit_default="°C" + unit_example_entity="input_number.max_comfort_temperature" + unit_example_value="18" %} {% include triggers/targets.md %}