diff --git a/source/_conditions/power.is_value.markdown b/source/_conditions/power.is_value.markdown new file mode 100644 index 000000000000..5b3c4fb25c0c --- /dev/null +++ b/source/_conditions/power.is_value.markdown @@ -0,0 +1,238 @@ +--- +title: "Power value" +condition: power.is_value +domain: power +description: "Tests the power value of one or more entities." +--- + +The **Power value** condition passes when a power reading meets the threshold you define. You can check whether the current reading is above, below, inside, or outside a range. + +Use **Power value** when you want an automation to continue only if the current load is suitable, such as waiting until an appliance is idle or avoiding another high-load action while household power use is already high. + +{% include integrations/labs_entity_triggers_note.md %} + +{% include conditions/ui_header.md %} + +To use **Power value** 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 power sensor is in. You can also select a device, a specific entity, or a label. +5. From the conditions shown for that target, select **Power value**. +6. Under **Threshold type**, set the power value 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 power value. For **In range** or **Outside range**, enter both a lower and upper bound. + - **Entity**: Use a sensor entity or a user-created [number helper](/integrations/input_number/) as the threshold. +7. Under **Condition passes if** (see [Behavior](#behavior-with-multiple-targets)), choose how multiple targeted sensors should behave. The default is **Any**. +8. Under **For at least**, set how long the reading must meet the threshold before the condition passes. Leave it at zero to pass immediately. +9. Select **Save**. + +### Options in the UI + +{% options_ui %} +Threshold type: + description: | + The power value 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 power value, or **Entity** to use a sensor or a user-created [number helper](/integrations/input_number/) 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. +For at least: + description: How long the reading must meet the threshold before the condition passes. The default is `0` (passes immediately). +{% endoptions_ui %} + +{% include conditions/yaml_header.md %} + +In YAML, refer to this condition as `power.is_value`. A basic example looks like this: + +{% example %} +condition: | + condition: power.is_value + target: + entity_id: sensor.main_power + options: + threshold: + type: below + value: + number: 2500 + unit_of_measurement: "W" +{% endexample %} + +This passes when the main power reading is below 2500 W. + +To check that multiple sensors are all inside a normal operating range: + +{% example %} +condition: | + condition: power.is_value + target: + entity_id: + - sensor.circuit_1_power + - sensor.circuit_2_power + options: + threshold: + type: between + value_min: + number: 100 + unit_of_measurement: "W" + value_max: + number: 1500 + unit_of_measurement: "W" + behavior: all +{% endexample %} + +This passes when both circuit power readings are between 100 W and 1500 W. + +To use a user-created {% term helper %} as a dynamic threshold that you can adjust without editing the automation: + +{% example %} +condition: | + condition: power.is_value + target: + entity_id: sensor.ev_charger_power + options: + threshold: + type: below + value: + entity: input_number.max_charger_power +{% endexample %} + +### Options in YAML + +{% options_yaml %} +threshold: + description: | + The power value 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 either a `number` and `unit_of_measurement` (for a literal power value) or an `entity` key. + - `type: below` (exclusive): Sets a maximum. The reading must be strictly below the threshold to pass. Provide `value` with either a `number` and `unit_of_measurement` (for a literal power value) 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 either a `number` and `unit_of_measurement` 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 either a `number` and `unit_of_measurement` or an `entity` key. + + When you use a literal number, add `unit_of_measurement` with one of the supported power units. + + Supported units are `mW`, `W`, `kW`, `MW`, `GW`, `TW`, and `BTU/h`. + required: true + type: map +behavior: + description: | + When multiple entities are targeted, controls how results combine: + + - `any` (default): passes if at least one targeted entity meets the threshold. + - `all`: passes only when every targeted entity meets the threshold. + required: false + type: string + default: any +for: + description: How long the reading must meet the threshold before the condition passes. Accepts a duration string in `HH:MM:SS` format. For example, `00:05:00` requires the reading to stay in range for 5 minutes. + required: false + type: string + default: "00:00:00" +{% endoptions_yaml %} + +{% include conditions/targets.md %} + +{% include conditions/behavior.md %} + +## Good to know + +- Use **Power value** to check the current load at the moment the condition runs. If you want to react when a reading changes or crosses a threshold, use [Power changed](/triggers/power.changed/) or [Power crossed threshold](/triggers/power.crossed_threshold/). +- Supported thresholds can use fixed values, a sensor with the power device class, a number entity with the power device class, or a user-created {% term helper %} from the [Input number integration](/integrations/input_number/). +- Supported power units are `mW`, `W`, `kW`, `MW`, `GW`, `TW`, and `BTU/h`. +- Entities that are `unavailable` or `unknown` are skipped when the condition is evaluated. With **Any**, at least one remaining valid entity must match. With **All**, every remaining valid entity must match. +- When you use a sensor or helper as a dynamic threshold, its current value is read when the condition runs. +- This condition works with sensors that have the power device class. + +{% include conditions/try_it.md %} + +{% include conditions/more_examples.md %} + +### Automation: only notify when the washing machine is really finished + +At 22:00, send a notification only if the washing machine power is below 3 W for at least 5 minutes. + +- **Trigger**: Time: 22:00 +- **Condition**: Power value (below 3 W) + - **Target**: Washing machine power sensor + - **For at least**: 00:05:00 +- **Action**: Send a notification message + - **Target**: My Device (`notify.my_device`) + +{% details "YAML example for checking that the washing machine is idle" %} + +{% example %} +automation: | + alias: "Notify only when the washing machine is really finished" + triggers: + - trigger: time + at: "22:00:00" + conditions: + - condition: power.is_value + target: + entity_id: sensor.washing_machine_power + options: + threshold: + type: below + value: + number: 3 + unit_of_measurement: "W" + for: "00:05:00" + actions: + - action: notify.send_message + target: + entity_id: notify.my_device + data: + message: "The washing machine is idle and the cycle appears to be finished." +{% endexample %} + +{% enddetails %} + +### Automation: only turn on the water heater boost when power use is low enough + +At 02:00, turn on the water heater boost switch only if the current household power use is below 2500 W. + +- **Trigger**: Time: 02:00 +- **Condition**: Power value (below 2500 W) + - **Target**: Main power sensor +- **Action**: Turn on switch + - **Target**: switch.water_heater_boost + +{% details "YAML example for checking power before turning on a water heater boost" %} + +{% example %} +automation: | + alias: "Turn on water heater boost when power use is low enough" + triggers: + - trigger: time + at: "02:00:00" + conditions: + - condition: power.is_value + target: + entity_id: sensor.main_power + options: + threshold: + type: below + value: + number: 2500 + unit_of_measurement: "W" + actions: + - action: switch.turn_on + target: + entity_id: switch.water_heater_boost +{% endexample %} + +{% enddetails %} + +{% include conditions/stuck.md %} + +{% include conditions/related.md %} diff --git a/source/_integrations/power.markdown b/source/_integrations/power.markdown index b6a74e0b92a7..706dd385bf37 100644 --- a/source/_integrations/power.markdown +++ b/source/_integrations/power.markdown @@ -11,4 +11,92 @@ ha_domain: power ha_integration_type: system --- -This {% term integration %} provides automation triggers and conditions for sensors and number entities with device class power. There are no configuration options for this integration. +This {% term integration %} provides automation triggers and conditions for entities with the power device class, like sensors and number entities. Use it when you want to react to how much power a device or circuit is using right now. There are no configuration options for this integration. + +## Power and energy + +- **Power** is the rate of energy use at a specific moment. It is usually shown in units like W or kW. Use the triggers and conditions in this integration when you want to react to a live load change, such as a washing machine finishing or a heater starting. +- **Energy** is the total amount used over time. It is usually shown in kWh. If you want to track accumulated usage, use an energy sensor or the [Energy dashboard](/docs/energy/). + +{% include integrations/triggers.md %} + +{% include integrations/conditions.md %} + +## Power automation examples + +Here are a few ways you can use power automations in Home Assistant. + +{% include docs/paste_yaml_tip.md %} + +### Automation: notify when the washing machine finishes + +When the washing machine power drops below 3 W for 5 minutes, send a notification so you know the cycle is done. + +- **Trigger**: Power crossed threshold + - **Target**: Washing machine power sensor + - **Threshold type**: Below 3 W + - **For at least**: 00:05:00 +- **Action**: Send a notification message + - **Target**: My Device (`notify.my_device`) + +{% details "YAML example for a washing machine finished notification" %} + +{% example %} +automation: | + alias: "Notify when the washing machine finishes" + triggers: + - trigger: power.crossed_threshold + target: + entity_id: sensor.washing_machine_power + options: + threshold: + type: below + value: + number: 3 + unit_of_measurement: "W" + for: "00:05:00" + actions: + - action: notify.send_message + target: + entity_id: notify.my_device + data: + message: "The washing machine cycle is finished." +{% endexample %} + +{% enddetails %} + +### Automation: only turn on the water heater boost when power use is low enough + +At 02:00, turn on the water heater boost switch only if the current household power use is below 2500 W. + +- **Trigger**: Time: 02:00 +- **Condition**: Power value (below 2500 W) + - **Target**: Main power sensor +- **Action**: Turn on switch + - **Target**: switch.water_heater_boost + +{% details "YAML example for checking power before turning on a water heater boost" %} + +{% example %} +automation: | + alias: "Turn on water heater boost when power use is low enough" + triggers: + - trigger: time + at: "02:00:00" + conditions: + - condition: power.is_value + target: + entity_id: sensor.main_power + options: + threshold: + type: below + value: + number: 2500 + unit_of_measurement: "W" + actions: + - action: switch.turn_on + target: + entity_id: switch.water_heater_boost +{% endexample %} + +{% enddetails %} diff --git a/source/_triggers/power.changed.markdown b/source/_triggers/power.changed.markdown new file mode 100644 index 000000000000..7033ff6bc767 --- /dev/null +++ b/source/_triggers/power.changed.markdown @@ -0,0 +1,210 @@ +--- +title: "Power changed" +trigger: power.changed +domain: power +description: "Triggers after one or more power values change." +related_triggers: + - power.crossed_threshold +--- + +The **Power changed** trigger fires when a power reading changes and the new value matches the threshold you set. You can react to any change, only when the new reading is above or below a limit, or only when it lands inside or outside a range. + +Use **Power changed** when you want to react to the latest power reading right away, such as noticing when an appliance starts drawing noticeable power or when a circuit moves outside its normal operating range. + +{% include integrations/labs_entity_triggers_note.md %} + +{% include triggers/ui_header.md %} + +To use **Power 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 power sensor is in. You can also select a device, a specific entity, or a label. +5. From the triggers shown for that target, select **Power changed**. +6. Under **Threshold type**, configure what kind of change fires the trigger: + - Select **Any change** to fire on any power change. + - 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 falls outside the range. + - For each option, you can enter a fixed power value, pick a sensor or number entity, or pick a user-created [number helper](/integrations/input_number/) as the threshold. +7. Select **Save**. + +### 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 power value or reference a sensor entity, a number entity, or a user-created [number helper](/integrations/input_number/). +{% endoptions_ui %} + +{% include triggers/yaml_header.md %} + +In YAML, **Power changed** is referred to as `power.changed`. A basic example looks like this: + +{% example %} +trigger: | + trigger: power.changed + target: + entity_id: sensor.washing_machine_power + options: + threshold: + type: above + value: + number: 10 + unit_of_measurement: "W" +{% endexample %} + +This fires whenever the washing machine power reading changes to a value above 10 W. To fire on any change regardless of direction or value, use `type: any` and omit `value`. + +To fire only when the new reading lands inside a normal operating range: + +{% example %} +trigger: | + trigger: power.changed + target: + entity_id: sensor.server_rack_power + options: + threshold: + type: between + value_min: + number: 150 + unit_of_measurement: "W" + value_max: + number: 350 + unit_of_measurement: "W" +{% endexample %} + +This fires whenever the server rack power reading changes to a value between 150 W and 350 W. + +To use a user-created {% term helper %} as a dynamic threshold that you can adjust without editing the automation: + +{% example %} +trigger: | + trigger: power.changed + target: + entity_id: sensor.oven_power + options: + threshold: + type: above + value: + entity: input_number.high_power_alert_threshold +{% endexample %} + +### Options in YAML + +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 power change (no additional keys needed). + - `type: above` (exclusive): Sets a minimum. Fires when the new reading is strictly above `value`. A reading equal to `value` does not fire the trigger. Provide `value` with either a `number` and `unit_of_measurement` (for a literal power value) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). + - `type: below` (exclusive): Sets a maximum. Fires when the new reading is strictly below `value`. A reading equal to `value` does not fire the trigger. Provide `value` with either a `number` and `unit_of_measurement` (for a literal power value) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). + - `type: between` (exclusive): Defines a range. Fires when the new 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 either a `number` and `unit_of_measurement` (for a literal power value) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). + - `type: outside` (inclusive): Defines an outside-range. Fires when the new 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 either a `number` and `unit_of_measurement` (for a literal power value) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). + + When you use a literal number, add `unit_of_measurement` with one of the supported power units. + + Supported units are `mW`, `W`, `kW`, `MW`, `GW`, `TW`, and `BTU/h`. + required: true + type: map +{% endoptions_yaml %} + +{% include triggers/targets.md %} + +## Good to know + +- Use **Power changed** when you want to react to the latest reading after it changes. If you need to react only when a reading crosses into or out of a threshold zone, use [Power crossed threshold](/triggers/power.crossed_threshold/) instead. +- Supported thresholds can use fixed values, a sensor with the power device class, a number entity with the power device class, or a user-created {% term helper %} from the [Input number integration](/integrations/input_number/). +- Supported power units are `mW`, `W`, `kW`, `MW`, `GW`, `TW`, and `BTU/h`. +- If a targeted entity is `unknown` or `unavailable`, it cannot fire the trigger until it reports a valid power value again. +- This trigger works with sensors that have the power device class. + +{% include triggers/try_it.md %} + +{% include triggers/more_examples.md %} + +### Automation: turn on a status light when the dryer starts drawing power + +When the dryer power changes to a value above 20 W, turn on a status light so you can see that a cycle is running. + +- **Trigger**: Power changed + - **Target**: Dryer power sensor + - **Threshold type**: Above 20 W +- **Action**: Turn on light + - **Target**: light.utility_room_status + +{% details "YAML example for a dryer running status light" %} + +{% example %} +automation: | + alias: "Turn on dryer status light when a cycle starts" + triggers: + - trigger: power.changed + target: + entity_id: sensor.dryer_power + options: + threshold: + type: above + value: + number: 20 + unit_of_measurement: "W" + actions: + - action: light.turn_on + target: + entity_id: light.utility_room_status +{% endexample %} + +{% enddetails %} + +### Automation: send a notification when a server rack leaves its normal power range + +When the server rack power changes to a value outside 150 W to 350 W, send a notification so you can check whether something unexpected is happening. + +- **Trigger**: Power changed + - **Target**: Server rack power sensor + - **Threshold type**: Outside range (150-350 W) +- **Action**: Send a notification message + - **Target**: My Device (`notify.my_device`) + +{% details "YAML example for a server rack power alert" %} + +{% example %} +automation: | + alias: "Alert when server rack power leaves its normal range" + triggers: + - trigger: power.changed + target: + entity_id: sensor.server_rack_power + options: + threshold: + type: outside + value_min: + number: 150 + unit_of_measurement: "W" + value_max: + number: 350 + unit_of_measurement: "W" + actions: + - action: notify.send_message + target: + entity_id: notify.my_device + data: + message: "Server rack power moved outside its normal range." +{% endexample %} + +{% enddetails %} + +{% include triggers/stuck.md %} + +{% include triggers/related.md %} diff --git a/source/_triggers/power.crossed_threshold.markdown b/source/_triggers/power.crossed_threshold.markdown new file mode 100644 index 000000000000..fcc7386e1772 --- /dev/null +++ b/source/_triggers/power.crossed_threshold.markdown @@ -0,0 +1,241 @@ +--- +title: "Power crossed threshold" +trigger: power.crossed_threshold +domain: power +description: "Triggers after one or more power values cross a threshold." +related_triggers: + - power.changed +--- + +The **Power crossed threshold** trigger fires when a power reading crosses into or out of a threshold zone that you define. You can detect when a reading moves above a level, drops below a level, enters a range, or leaves a range. + +Use **Power crossed threshold** when the crossing moment matters, such as when an appliance starts drawing noticeable power, when a washing machine finishes, or when a circuit load moves into a range that needs attention. + +When you target more than one entity, the trigger's **Trigger when** option controls when it fires. + +{% include integrations/labs_entity_triggers_note.md %} + +{% include triggers/ui_header.md %} + +To use **Power 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 power sensor is in. You can also select a device, a specific entity, or a label. +5. From the triggers shown for that target, select **Power crossed threshold**. +6. Under **Threshold type**, configure the zone the reading must cross 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. + - For each option, you can enter a fixed power value, pick a sensor or number entity, or pick a user-created [number helper](/integrations/input_number/) as the threshold. +7. Under **Trigger when** (see [Behavior](#behavior-with-multiple-targets)), choose how multiple targeted sensors should behave. The default is **Each**. +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**. + +### 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 power value or reference a sensor entity, a number entity, or a user-created [number helper](/integrations/input_number/). +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. For example, set it to `0:05:00` to wait 5 minutes before running the automation. Default is `0` (fires immediately). +{% endoptions_ui %} + +{% include triggers/yaml_header.md %} + +In YAML, **Power crossed threshold** is referred to as `power.crossed_threshold`. A basic example looks like this: + +{% example %} +trigger: | + trigger: power.crossed_threshold + target: + entity_id: sensor.washing_machine_power + options: + threshold: + type: below + value: + number: 3 + unit_of_measurement: "W" +{% endexample %} + +This fires whenever the washing machine power reading crosses below 3 W. + +To fire when a reading leaves a normal operating range: + +{% example %} +trigger: | + trigger: power.crossed_threshold + target: + entity_id: sensor.main_power + options: + threshold: + type: outside + value_min: + number: 500 + unit_of_measurement: "W" + value_max: + number: 3500 + unit_of_measurement: "W" +{% endexample %} + +This fires whenever the main power reading crosses outside the 500 W to 3500 W range. + +To use a user-created {% term helper %} as a dynamic threshold that you can adjust without editing the automation: + +{% example %} +trigger: | + trigger: power.crossed_threshold + target: + entity_id: sensor.ev_charger_power + options: + threshold: + type: above + value: + entity: input_number.high_power_alert_threshold + behavior: first +{% endexample %} + +### Options in YAML + +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 either a `number` and `unit_of_measurement` (for a literal power value) 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 either a `number` and `unit_of_measurement` (for a literal power value) 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 either a `number` and `unit_of_measurement` (for a literal power value) 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 either a `number` and `unit_of_measurement` (for a literal power value) or an `entity` key (for an `input_number`, `number`, or `sensor` entity). + + When you use a literal number, add `unit_of_measurement` with one of the supported power units. + + Supported units are `mW`, `W`, `kW`, `MW`, `GW`, `TW`, and `BTU/h`. + required: true + type: map +behavior: + 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 threshold crossing. + - `all`: fires only after every targeted entity crosses the threshold. + required: false + type: string + default: each +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` waits 5 minutes before the trigger runs. + required: false + type: string + default: "00:00:00" +{% endoptions_yaml %} + +{% include triggers/targets.md %} + +{% include triggers/behavior.md %} + +## Good to know + +- Use **Power crossed threshold** when you care about the moment a reading crosses a level or range boundary. If you want to react to every matching reading change instead, use [Power changed](/triggers/power.changed/). +- Supported thresholds can use fixed values, a sensor with the power device class, a number entity with the power device class, or a user-created {% term helper %} from the [Input number integration](/integrations/input_number/). +- Supported power units are `mW`, `W`, `kW`, `MW`, `GW`, `TW`, and `BTU/h`. +- If a targeted entity is `unknown` or `unavailable`, it cannot contribute to the trigger until it reports a valid power value again. +- This trigger works with sensors that have the power device class. + +{% include triggers/try_it.md %} + +{% include triggers/more_examples.md %} + +### Automation: notify when the washing machine finishes + +When the washing machine power crosses below 3 W and stays there for 5 minutes, send a notification so you know the cycle is done. + +- **Trigger**: Power crossed threshold + - **Target**: Washing machine power sensor + - **Threshold type**: Below 3 W + - **For at least**: 00:05:00 +- **Action**: Send a notification message + - **Target**: My Device (`notify.my_device`) + +{% details "YAML example for a washing machine finished notification" %} + +{% example %} +automation: | + alias: "Notify when the washing machine finishes" + triggers: + - trigger: power.crossed_threshold + target: + entity_id: sensor.washing_machine_power + options: + threshold: + type: below + value: + number: 3 + unit_of_measurement: "W" + for: "00:05:00" + actions: + - action: notify.send_message + target: + entity_id: notify.my_device + data: + message: "The washing machine cycle is finished." +{% endexample %} + +{% enddetails %} + +### Automation: turn on a warning light when a heater starts drawing high power + +When a space heater power reading crosses above 1500 W, turn on a warning light so the load is easy to notice. + +- **Trigger**: Power crossed threshold + - **Target**: Space heater power sensor + - **Threshold type**: Above 1500 W +- **Action**: Turn on light + - **Target**: light.high_load_warning + +{% details "YAML example for a high-load heater warning" %} + +{% example %} +automation: | + alias: "Turn on warning light when heater power gets high" + triggers: + - trigger: power.crossed_threshold + target: + entity_id: sensor.space_heater_power + options: + threshold: + type: above + value: + number: 1500 + unit_of_measurement: "W" + actions: + - action: light.turn_on + target: + entity_id: light.high_load_warning +{% endexample %} + +{% enddetails %} + +{% include triggers/stuck.md %} + +{% include triggers/related.md %}