node-red-contrib-power-saver 3.6.1 → 4.0.0

package/docs/examples/example-grid-tariff-capacity-part.md

@@ -1,69 +1,253 @@
 # Capacity part of grid tariff
 
-I Norway, there has been introduced a monthly fee for grid capacity. The purpose is to get people to avoid using large capacities at any time.
-The fee is calculated based on the average consumption per hour. The maximum average consumption for each day is calculated. Then the average of the three highest days for the month is used to decide your capacity fee.
+::: danger Bug-fix 12. September 2022
 
-The capacity is divided in steps, so if your average of the 3 worst days is over the step limit, your fee is picked from that step.
+::: details A bug was found 12. sep 2022. Here is how to fix:
 
-Here is an example how this can be controlled. The axample contains several features, and yuo may not want to use them all, so it is a good idea to read through it all before you decide how to use it.
+### 1. Node "Find highest per day":
+
+Replace this line:
+
+```js
+const highestToday = days.get(new Date().getDate());
+```
+
+With this code:
+
+```js
+const highestToday = days.get(new Date().getDate()) ?? {
+  consumption: 0,
+  from: null,
+};
+```
+
+This will set the `highestToday` to 0 during the first hour.
+
+### 2. Node "Calculate values":
+
+Above this line:
+
+```js
+  function calculateLevel(hourEstimate, ...
+```
+
+Insert this code:
+
+```js
+function isNull(value) {
+  return value === null || value === undefined;
+}
+```
+
+Further down the code you can find these 3 lines with 4 lines between:
+
+```js
+if (!highestPerDay) {
+if (!highestToday) {
+if (!hourEstimate) {
+```
+
+Change these to:
+
+```js
+if (isNull(highestPerDay)) {
+if (isNull(highestToday)) {
+if (isNull(hourEstimate)) {
+```
+
+Then these will not fail the first hour.
+
+### 3. Node "Build query for consumption":
+
+Find this line:
+
+```js
+const hour = time.getMinutes(); // NB Change to getMinutes()
+```
+
+Change it to:
+
+```js
+const hour = time.getHours();
+```
+
+The bug fixed on no. 3 does so data for hours are read every minute,
+instead of every hour. This is not necessary.
+However, it does not lead to any error.
+:::
+
+## Introduction
+
+I Norway, there has been introduced a monthly fee for grid capacity.
+The purpose is to get people to avoid peaks of high capacity usage.
+
+The fee is calculated based on the average consumption per hour (kWh).
+For each day, the worst hour is used, that is the hour with highest consumption that day.
+Then the 3 days where this number is highest (the 3 highest) is used.
+The average of these 3 days is calculated, and the result decides what capacity step you will pay for.
+
+The steps are for example like this:
+
+- 0-2 kW
+- 2-5 kW
+- 5-10 kW
+- 10-15 kW
+- 15-20 kW
+
+This may be different for different grid providers.
+
+If, for example, the average of the 3 worst days is 6 kW, you pay for step 5-10 kW.
+
+Here is an example how this can be controlled. The example contains several features,
+and you may not want to use them all, so it is a good idea to read through it all before you decide how to use it.
+
+![Capacity Flow](../images/example-capacity-flow.png)
+
+The first part of nodes (upper left) is used to read consumption from Tibber and to perform all calculations.
+The second part (right) is used to update a set of sensors in HA. You can use those sensor for many
+purposes related to the grid capacity.
+The third part (bottom left) is used to take actions in order to reduce power consumption,
+or to reset actions when the consumption is lowered.
+
+You may use the whole example, or only part of it, so you should read through the whole documentation before you start,
+so you can decide what to use and how to use it.
+
+The complex parts are solved by scripts in the function nodes, and you will have to change parts of them to use it all.
+
+::: warning No guarantee
+There is no guarantee that this works, so use at your own risk.
+:::
 
 ## Requirements
 
 You need the following to be able to use this example:
 
+- Home Assistant with Node-RED
 - Tibber Pulse to measure consumption continuously.
 - Tibber subscription to get consumption data per hour.
 - Token to access Tibber API.
 - [Node-RED Companion Integration](https://github.com/zachowj/hass-node-red)
-- Tibber nodes in Node-RED.
+- Tibber nodes in Node-RED [(node-red-contrib-tibber-api)](https://flows.nodered.org/node/node-red-contrib-tibber-api).
 
 If you have the same information from other sources, you may be able to adapt the example.
 
 ## Features
 
-- Show status as Ok, Warning or Alarm for the current consumption (estimate calculated for the current hour).
-- Show current step, that is the step that you already are on based on consumption previously this month.
-- Control sensors in HA that you can use to take action to reduce consumption the current hour.
+- 15-20 sensors in HA showing information related to the capacity and the calculation, including:
+  - Status Ok, Warning or Alarm related to current consumption compared to the next step.
+  - Alarm level 0-9 based on how serious the current consumption is.
+  - Current step based on usage the whole month.
+  - The highest consumption any hour today.
+  - Reduction required to avoid breaking the limit.
+  - Reduction recommended to reduce risk of breaking he limit.
+  - Estimates for the current hour.
+  - Current consumption based on average the last minute (can be configured).
+- Automatically take actions to reduce consumption if it is recommended or required.
+- Automatically reset actions if the consumption is sufficiently reduced.
+- Log actions taken to a file
 
 ## Algorithm
 
-The algorithm is calculating a state that can be:
+The consumption is measured by Tibber Pulse continuously (every 2 seconds),
+and is used to calculate average consumption the last minute.
+(Can be configured to another number of minutes.)
+**It is assumed that you will have this consumption the rest of the current hour.**
+Based on the real consumption until now this hour, and the assumed consumption the
+rest of the hour, the total for the current hour is estimated. This is the `hourEstimate`.
 
-- Ok - Current estimate will not bring you over to another step.
-- Warning - Current estimate may affect the step, if combined with high consumption later this month.
-- Alarm - Current estimate will bring you over to another step.
+The highest hour previously this day is found as `highestToday`.
 
-The current consumption is measured continuously (every 2 seconds), along with the total consumption for the current hour until current time.
-The consumption for the rest of the current hour is estimated, assumed to be the same in average as the average consumption for the last minute (can be configured to several minutes). Based on this, the total consumption for the current hour is estimated.
+The highest hour for each day this month is found, and the 3 highest is used
+in the calculation as the `highestCounting`.
 
-Then the current hour is compared to the other hours today. If it is not the worst, status is Ok, as it will not affect the fee.
+Then the `hourEstimate` is compared to those other numbers to calculate an alarm level.
 
-If the current hour is todays worst, it is ranked together with the other days this month. If today is ranked as 4 or better, where 1 is the worst this month, then status is Ok. It will not affect the fee.
+If the current hour is todays worst, it is ranked together with the other days this month.
+If today is ranked as 4 or better, where 1 is the worst this month, then status is Ok.
+It will not affect the fee.
 
 The `currentStep` is decided based on the 3 worst days, including today, but not considering the current hour.
 
-If today is ranked as 1, 2 or 3, it may affect the fee. Then the average of the three worst days, including this hour, is calculated. This is `currentMonthlyEstimate`. So, if the current hour is ranked as 3, and the `currentMonthlyEstimate` is still within `currentStep`, status is still Ok, as the current hour will not participate in braking the step limit.
+If today is ranked as 1, 2 or 3, it may affect the fee. Then the average of the three worst days, including this hour, is calculated. This is `currentMonthlyEstimate`.
+
+Other sensor values are calculated based on values available.
+See description for each of them for details.
+
+## Calculated sensor values
+
+The `Calculate values` node creates a payload with values that are used to create
+sensors in Home Assistant. There is one `entity` node for each sensor value.
+You may delete the entity nodes for sensor values you don't need.
+
+Here is a description of each of those sensor values.
+
+### Status
+
+The status of the current hour as text: `Ok`, `Warning` or `Alarm`.
+
+`Alarm` means that if you do not reduce the consumption, you will break the limit of the next step.
+
+`Warning` means that there is an increased risk for breaking the limit.
+
+`Ok` means you are pretty safe.
+
+### Ok
+
+A boolean value, `true` if the status is `Ok`, `false` if not.
+
+### Warning
+
+A boolean value, `true` if the status is `Warning`, `false` if not.
+
+### Alarm
 
-If today is ranked as 1, 2 or 3, and the `currentMonthlyEstimate` is over the `currentStep`, then the status is Alarm.
+A boolean value, `true` if the status is `Alarm`, `false` if not.
 
-Else the status is Warning. That is if today is ranked as 1 or 2, but `currentMonthlyEstimate` is still under `currentStep`. In this case, the current hour makes the situation worse, and can potentially participate in breaking the limit together with a worse hour coming later this month.
+You can configure the constant `ALARM` to the lowest level that will cause status `Alarm`. Default is `8`,
+meaning you have a small buffer (the `BUFFER`).
 
-## Output
+### Alarm Level
 
-The last step in the flow provides the following output:
+A number from 0 to 9, meaning as follows:
 
-| Name                   | Description                                                              |
-| ---------------------- | ------------------------------------------------------------------------ |
-| status                 | The status of the current hour (Ok, Warning or Alarm).                   |
-| highestPerDay          | An array with the worst hour for each day this month                     |
-| highestCounting        | An array with the 3 worst days this month, including passed hours today. |
-| highestToday           | The worst hour until now today, not including current hour.              |
-| currentMonthlyEstimate | The average of the three worst days, including this hour.                |
-| hourEstimate           | The estimate for the current hour.                                       |
-| currentStep            | The upper limit of the step we are currently on.                         |
-| currentHourRanking     | The rank of the current hour, from 0 to 4. See below.                    |
+| Level | Description                                                                                                                                                                                                                     |
+| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 0     | You're good, either because consumption is low or because there was a worse hour earlier today.                                                                                                                                 |
+| 9     | The current consumption will lead to breaking the limit for the next step, if continued.                                                                                                                                        |
+| 8     | Same as `9`but with a buffer you can configure to reduce risk. The buffer is a constant named `BUFFER`, and the default value is 0.5 kWh                                                                                        |
+| 7     | The `hourEstimate` (estimate for the hour) is higher than the limit for the next step, but since previous consumption has been low, the average of the 3 worst is below the limit, so you will not break the limit **yet (!)**. |
+| 6     | Same as 7 but with a the same buffer as for alarm level `8`                                                                                                                                                                     |
+| 5     | The `hourEstimate` is the worst this month, and it is only a _safe zone_ away from breaking the limit. The safe zone can be configured using the constant called `SAFE_ZONE`, default 2 kWh.                                    |
+| 4     | The `hourEstimate` is the second to worst this month, and it is only a _safe zone_ away from breaking the limit.                                                                                                                |
+| 3     | The `hourEstimate` is the third to worst this month, and it is only a _safe zone_ away from breaking the limit.                                                                                                                 |
+| 2     | The `hourEstimate` is the worst this month. Consumption may still be low.                                                                                                                                                       |
+| 1     | The `hourEstimate` is the second to worst this month. Consumption may still be low.                                                                                                                                             |
 
-### currentHourRanking
+### Current Step
+
+Shows the step you are currently on (under), that is the limit you do not want to break.
+The steps are configured using the constant `STEPS` in the script.
+The default is
+
+```
+const STEPS = [2, 5, 10, 15, 20]
+```
+
+::: warning Configure steps
+You must edit the `STEPS`constant in the script.
+Set it to the relevant steps for your grid supplier.
+You should omit steps that you do not plan to stay under,
+so you avoid alarms and actions for that step in the beginning of the month.
+:::
+
+### Hour Estimate
+
+The estimated consumption for the current hour (`hourEstimate`).
+This is calculated as real consumption earlier this hour plus estimated consumption for the rest of the hour.
+
+### Current Hour Ranking
+
+A number (0-4) ranking the current hour with the 3 highest hours this month.
 
 The current hour ranking has the following meaning:
 
@@ -75,43 +259,70 @@ The current hour ranking has the following meaning:
 | 3     | This is estimated to be the third worst hour in the month.                         |
 | 4     | This hour is estimated to be the worst today, but not one of the top 3 this month. |
 
-::: warning
+::: warning Max ranking value
 The highest value here, 4, is based on the value of `MAX_COUNTING` in the `Find highest per day` node.
 If you change `MAX_COUNTING`, the values here will also change.
 :::
 
-### alarmLevel TODO
+### Monthly Estimate
+
+The average of the 3 worst hours so far this month, in kWh.
+
+### Highest Today
+
+The consumption in kWh of the worst hour today, not including the current hour.
+
+### Highest Today Hour
+
+The start time of the worst hour today (Highest Today).
 
-| Value | Description                                                                                                                 |
-| ----- | --------------------------------------------------------------------------------------------------------------------------- |
-| 0     | There is nothing to worry about.                                                                                            |
-| 1     | The estimate for the current hour sets this as the second to worst hour this month, but it is still way under the next step |
-| 2     | The estimate for the current hour sets this as the worst hour this month, but it is still way under the next step           |
-| 3     | The estimate for the current hour is close to the limit for the next step                                                   |
-| 4     | The estimate for the current hour is very close to the limit for the next step                                              |
-| 5     | The estimate for the current hour is over the limit for the next step                                                       |
-| 6     | The estimate for the current hour is way over the limit for the next step                                                   |
-| 6     | This hour increases the estimate for the month                                                                              |
+### Reduction Required
 
-hourEstimate
-maxToday
-highestCounting (1, 2, 3)
-highestCountingAverage
-nextStep
+The number of kW you must reduce the rest of the hour in order to not get alarm (break the limit),
+based on `hourEstimate`.
 
-hourEstimate < maxToday
-hourEstimate > maxToday && hourEstimate < highestCounting[2]
-maxToday < hourEstimate < nextStep
-maxToday < hourEstimate < highestCounting[2]
-maxToday < hourEstimate < highestCounting[1]
-maxToday < hourEstimate < highestCounting[0]
+This follows the `Alarm` state, and thus also the `ALARM` constant, so if
+alarm level `8` gives status `Alarm`, reduction required is also set when the alarm level is `8`.
+However, if you reconfigure `ALARM` to be only on level `9`, then reduction required is only set when
+the alarm level is `9`.
 
-You can define the limits for `close` and `very close` to the next step, and the limit for `way over` the next step.
+Please note that this takes the time in consideration, so if the `hourEstimate` is 1 kWh
+over the limit, and the time left of the hour is 15 minutes, the reduction required will
+be 4 kW. You must reduce the consumption with 4kW in order to save 1 kWh during 15 minutes.
 
-If the current hour is
+### Reduction Recommended
+
+The number of kW you must reduce the rest of the hour in order to stay under alarm level 3,
+based on `hourEstimate`. Calculated the same way as reduction required.
+
+### Increase Possible
+
+The number of kW you can increase consumption and still stay within the configured safe zone.
+If alarm level is > 2, this value will be 0. You will never have increase possible at the same time as
+reduction recommended (nor reduction required).
+
+### Estimate Rest Of Hour
+
+The estimated consumption in kWh for the rest of the hour.
+
+### Consumption Accumulated Hour
+
+The actual consumption in kWh until now this hour.
+
+### Time Left
+
+The time left of the current hour in seconds.
+
+### Consumption Now
+
+The current consumption, measured as average the last minute.
+Can be set to another number of minutes using the `ESTIMATION_TIME_MINUTES` constant in
+the `Collect estimate for hour` node.
 
 ## Node description
 
+Here is a description of each node in the example.
+
 ### Get live data
 
 This is a `tibber-feed` node. It sets up a subscription of live Tibber data from Tibber Pulse, and uses this data to run the automation. Tick the following check boxes:
@@ -142,6 +353,69 @@ This is a function node that is used to build a Tibber query. It runs for all th
 This node needs the tibber home id, so you must find it in the [Tibber Developer Pages](https://developer.tibber.com/) and set the vale of `TIBBER_HOME_ID` in the beginning of the code.
 :::
 
+::: details Code
+
+<CodeGroup>
+  <CodeGroupItem title="On Start">
+
+```js
+context.set("previousHour", undefined);
+```
+
+  </CodeGroupItem>
+
+  <CodeGroupItem title="On Message" active>
+
+```js
+/*
+   Calculate number of hours to receive consumption for,
+   that is number of hours in the month until now.
+   Constructs a tibber query to get consumption per hour.
+*/
+
+const TIBBER_HOME_ID = "put your tibber ome id here";
+
+const timestamp = msg.payload.timestamp;
+
+// Stop if hour has not changed
+const time = new Date(timestamp);
+const hour = time.getHours();
+const previousHour = context.get("previousHour");
+if (previousHour !== undefined && hour === previousHour) {
+  return;
+}
+context.set("previousHour", hour);
+
+// Calculate number of hours to query
+const date = time.getDate() - 1;
+const hour2 = time.getHours();
+const count = date * 24 + hour2;
+
+// Build query
+const query = `
+{
+  viewer {
+    home (id: "${TIBBER_HOME_ID}") {
+      consumption(resolution: HOURLY, last: ${count}) {
+        nodes {
+          from
+          consumption
+        }
+      }
+    }
+  }
+}
+`;
+
+msg.payload = query;
+return msg;
+```
+
+  </CodeGroupItem>
+</CodeGroup>
+
+:::
+
 ### Get consumption
 
 This is a `tibber-query` node used to get consumption per hour for passed hours. It takes a Tibber query as input, and sends the result as output. The query is built by the previous node.
@@ -186,24 +460,104 @@ It must contain data for every hour from the beginning of the month until the la
 
 ### Collect estimate for hour
 
-This is a function node that receives all the live data and estimates the consumption for the rest of the current hour. It sums up the actual consumption from the beginning of the hour until the current time, and adds the estimate for the rest of the hour, giving a total estimate for the hour.
+This is a function node that receives all the live data and estimates the consumption for the rest of the current hour.
+It sums up the actual consumption from the beginning of the hour until the current time,
+and adds the estimate for the rest of the hour, giving a total estimate for the hour.
 
 In the beginning of the code, there is a constant `ESTIMATION_TIME_MINUTES` that you can use to decide how many minutes that is used
 to calculate assumed average consumption.
 
 The function keeps a buffer with all readings for the last period of length given with `ESTIMATION_TIME_MINUTES`.
-It uses this buffer to calculate the average consumption for the period. It uses the result and estimates the consumption for the rest of the hour, assuming that the consumption will be the same.
+It uses this buffer to calculate the average consumption for the period.
+It uses the result and estimates the consumption for the rest of the hour, assuming that the consumption will be the same.
 
 As outputs it sends the following:
 
-| Name                   | Description                                                                                                                          |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| accumulatedConsumption | Accumulated consumption the current day.                                                                                             |
-| periodSec              | Period the average is calculated for, in seconds. It will increase in the beginning, until it reaches `ESTIMATION_TIME_MINUTES * 60` |
-| consumptionInPeriod    | Consumption in the last `periodSec` seconds. Used as estimate for the remaining of the hour.                                         |
-| timeLeftSec            | Number of seconds left in the current hour.                                                                                          |
-| consumptionLeft        | Estimated consumption the remaining of the hour.                                                                                     |
-| hourEstimate           | The estimated consumption for the total hour.                                                                                        |
+| Name                             | Description                                                                                                                                      |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `accumulatedConsumption`         | Accumulated consumption the current day                                                                                                          |
+| `accumulatedConsumptionLastHour` | Accumulated consumption the current hour.                                                                                                        |
+| `periodMs`                       | Period the average is calculated for, in milliseconds. It will increase in the beginning, until it reaches `ESTIMATION_TIME_MINUTES * 60 * 1000` |
+| `consumptionInPeriod`            | Consumption in the last `periodMs` milliseconds. Used as estimate for the remaining of the hour.                                                 |
+| `averageConsumptionNow`          | Consumption the last minute (or `ESTIMATION_TIME_MINUTES` minutes).                                                                              |
+| `timeLeftMs`                     | Number of milliseconds left in the current hour.                                                                                                 |
+| `consumptionLeft`                | Estimated consumption the remaining of the hour.                                                                                                 |
+| `hourEstimate`                   | The estimated consumption for the total hour.                                                                                                    |
+| `currentHour`                    | The time of the current hour.                                                                                                                    |
+
+::: details Code
+
+<CodeGroup>
+  <CodeGroupItem title="On Start">
+
+```js
+context.set("buffer", []);
+```
+
+  </CodeGroupItem>
+
+  <CodeGroupItem title="On Message" active>
+
+```js
+// Number of minutes used to calculate assumed consumption:
+const ESTIMATION_TIME_MINUTES = 1;
+
+const buffer = context.get("buffer") || [];
+
+// Add new record to buffer
+const time = new Date(msg.payload.timestamp);
+const timeMs = time.getTime();
+const accumulatedConsumption = msg.payload.accumulatedConsumption;
+const accumulatedConsumptionLastHour = msg.payload.accumulatedConsumptionLastHour;
+buffer.push({ timeMs, accumulatedConsumption });
+
+const currentHour = new Date(msg.payload.timestamp);
+currentHour.setMinutes(0);
+currentHour.setSeconds(0);
+
+// Remove too old records from buffer
+const maxAgeMs = ESTIMATION_TIME_MINUTES * 60 * 1000;
+let oldest = buffer[0];
+while (timeMs - oldest.timeMs > maxAgeMs) {
+  buffer.splice(0, 1);
+  oldest = buffer[0];
+}
+context.set("buffer", buffer);
+
+// Calculate buffer
+const periodMs = buffer[buffer.length - 1].timeMs - buffer[0].timeMs;
+const consumptionInPeriod = buffer[buffer.length - 1].accumulatedConsumption - buffer[0].accumulatedConsumption;
+if (periodMs === 0) {
+  return; // First item in buffer
+}
+
+// Estimate remaining of current hour
+const timeLeftMs = 60 * 60 * 1000 - (time.getMinutes() * 60000 + time.getSeconds() * 1000 + time.getMilliseconds());
+const consumptionLeft = (consumptionInPeriod / periodMs) * timeLeftMs;
+const averageConsumptionNow = (consumptionInPeriod / periodMs) * 60 * 60 * 1000;
+
+// Estimate total hour
+const hourEstimate = accumulatedConsumptionLastHour + consumptionLeft + 0; // Change for testing
+
+msg.payload = {
+  accumulatedConsumption,
+  accumulatedConsumptionLastHour,
+  periodMs,
+  consumptionInPeriod,
+  averageConsumptionNow,
+  timeLeftMs,
+  consumptionLeft,
+  hourEstimate,
+  currentHour,
+};
+
+return msg;
+```
+
+  </CodeGroupItem>
+</CodeGroup>
+
+:::
 
 ### Find highest per day
 
@@ -218,55 +572,582 @@ Based on the result from the tibber query, gives the following output:
 
 Output is sent when the query is run, that is on startup and when the hour changes.
 
-### Check for breach
+::: details Code
+
+<CodeGroup>
+  <CodeGroupItem title="On Message" active>
+
+```js
+const MAX_COUNTING = 3;
+const hours = msg.payload.viewer.home.consumption.nodes;
+const days = new Map();
+hours.forEach((h) => {
+  const date = new Date(h.from).getDate();
+  if (!days.has(date) || h.consumption > days.get(date).consumption) {
+    days.set(date, { from: h.from, consumption: h.consumption });
+  }
+});
+const highestToday = days.get(new Date().getDate()) ?? 0;
+const highestPerDay = [...days.values()].sort((a, b) => b.consumption - a.consumption);
+const highestCounting = highestPerDay.slice(0, MAX_COUNTING);
+const currentMonthlyMaxAverage =
+  highestCounting.length === 0
+    ? 0
+    : highestCounting.reduce((prev, val) => prev + val.consumption, 0) / highestCounting.length;
+msg.payload = {
+  highestPerDay,
+  highestCounting,
+  highestToday,
+  currentMonthlyMaxAverage,
+};
+return msg;
+```
+
+  </CodeGroupItem>
+</CodeGroup>
+
+:::
+
+### Calculate values
+
+This is where calculation is done to produce all the output sensor values.
+
+In the beginning of the script there are some constants you can configure:
+
+```js
+const HA_NAME = "homeAssistant"; // Your HA name
+const STEPS = [2, 5, 10, 15, 20]; // Grid tariff steps in kWh
+const MAX_COUNTING = 3; // Number of days to calculate month average of
+const BUFFER = 0.5; // kWh - Closer to limit increases alarm level
+const SAFE_SONE = 2; // kWh - Further from limit reduces level
+const ALARM = 8; // Min level that causes status to be alarm
+```
+
+The `HA_NAME` must be set to the name you have given your Home Assistant. One place to find this is in Node-RED,
+in the `Context Data` window (next to the `Debug` window), under `Global`, click the refresh button and see the `homeassistant` object.
+Find the name used to the right.
+In this example the value you are looking for is `homeAssistant`:
+
+![Global context window](../images/global-context-window.png)
+
+You must configure the `STEPS` array to contain steps relevant for you.
+You should omit steps you do not plan to go under, to avoid non-necessary actions and warnings.
+
+See [Calculated sensor values](#calculated-sensor-values) for description of the output.
+
+::: details Code
+
+<CodeGroup>
+  <CodeGroupItem title="On Message" active>
+
+```js
+const HA_NAME = "homeAssistant"; // Your HA name
+const STEPS = [2, 5, 10, 15, 20];
+const MAX_COUNTING = 3; // Number of days to calculate month
+const BUFFER = 0.5; // Closer to limit increases level
+const SAFE_ZONE = 2; // Further from limit reduces level
+const ALARM = 8; // Min level that causes status to be alarm
+
+const ha = global.get("homeassistant")[HA_NAME];
+if (!ha.isConnected) {
+  return;
+}
+
+function isNull(value) {
+  return value === null || value === undefined;
+}
+
+function calculateLevel(hourEstimate, currentHourRanking, highestCountingAverageWithCurrent, nextStep) {
+  if (currentHourRanking === 0) {
+    return 0;
+  }
+  if (highestCountingAverageWithCurrent > nextStep) {
+    return 9;
+  }
+  if (highestCountingAverageWithCurrent > nextStep - BUFFER) {
+    return 8;
+  }
+  if (hourEstimate > nextStep) {
+    return 7;
+  }
+  if (hourEstimate > nextStep - BUFFER) {
+    return 6;
+  }
+  if (currentHourRanking === 1 && nextStep - hourEstimate < SAFE_ZONE) {
+    return 5;
+  }
+  if (currentHourRanking === 2 && nextStep - hourEstimate < SAFE_ZONE) {
+    return 4;
+  }
+  if (currentHourRanking === 3 && nextStep - hourEstimate < SAFE_ZONE) {
+    return 3;
+  }
+  if (currentHourRanking === 1) {
+    return 2;
+  }
+  if (currentHourRanking === 2) {
+    return 1;
+  }
+  return 0;
+}
+
+if (msg.payload.highestPerDay) {
+  context.set("highestPerDay", msg.payload.highestPerDay);
+  context.set("highestCounting", msg.payload.highestCounting);
+  context.set("highestToday", msg.payload.highestToday);
+  context.set("currentMonthlyMaxAverage", msg.payload.currentMonthlyMaxAverage);
+  node.status({ fill: "green", shape: "ring", text: "Got ranking" });
+  return;
+}
+
+const highestPerDay = context.get("highestPerDay");
+const highestCounting = context.get("highestCounting");
+const highestToday = context.get("highestToday");
+const currentMonthlyMaxAverage = context.get("currentMonthlyMaxAverage");
+const hourEstimate = msg.payload.hourEstimate;
+const timeLeftMs = msg.payload.timeLeftMs;
+const timeLeftSec = timeLeftMs / 1000;
+const periodMs = msg.payload.periodMs;
+const accumulatedConsumption = msg.payload.accumulatedConsumption;
+const accumulatedConsumptionLastHour = msg.payload.accumulatedConsumptionLastHour;
+const consumptionLeft = msg.payload.consumptionLeft;
+const averageConsumptionNow = msg.payload.averageConsumptionNow;
+const currentHour = msg.payload.currentHour;
+
+if (timeLeftSec === 0) {
+  return null;
+}
+
+if (isNull(highestPerDay)) {
+  node.status({ fill: "red", shape: "dot", text: "No highest per day" });
+  return;
+}
+if (isNull(highestToday)) {
+  node.status({ fill: "red", shape: "dot", text: "No highest today" });
+  return;
+}
+if (isNull(hourEstimate)) {
+  node.status({ fill: "red", shape: "dot", text: "No estimate" });
+  return;
+}
+
+const currentStep = STEPS.reduceRight(
+  (prev, val) => (val > currentMonthlyMaxAverage ? val : prev),
+  STEPS[STEPS.length - 1]
+);
+
+// Set currentHourRanking
+let currentHourRanking = MAX_COUNTING + 1;
+for (let i = highestCounting.length - 1; i >= 0; i--) {
+  if (hourEstimate > highestCounting[i].consumption) {
+    currentHourRanking = i + 1;
+  }
+}
+if (hourEstimate < highestToday.consumption) {
+  currentHourRanking = 0;
+}
+
+const current = { from: currentHour, consumption: hourEstimate };
+const highestCountingWithCurrent = [...highestCounting, current]
+  .sort((a, b) => b.consumption - a.consumption)
+  .slice(0, highestCounting.length);
+const currentMonthlyEstimate =
+  highestCountingWithCurrent.length === 0
+    ? 0
+    : highestCountingWithCurrent.reduce((prev, val) => prev + val.consumption, 0) / highestCountingWithCurrent.length;
+
+// Set alarm level
+const alarmLevel = calculateLevel(hourEstimate, currentHourRanking, currentMonthlyEstimate, currentStep);
+
+// Evaluate status
+const status = alarmLevel >= ALARM ? "Alarm" : alarmLevel > 0 ? "Warning" : "Ok";
+
+// Calculate reduction
+const reductionRequired =
+  alarmLevel < ALARM
+    ? 0
+    : (Math.max((currentMonthlyEstimate - currentStep) * highestCounting.length, 0) * 3600) / timeLeftSec;
+const reductionRecommended =
+  alarmLevel < 3 ? 0 : (Math.max(hourEstimate + SAFE_ZONE - currentStep, 0) * 3600) / timeLeftSec;
+
+// Calculate increase possible
+const increasePossible =
+  alarmLevel >= 3 ? 0 : (Math.max(currentStep - hourEstimate - SAFE_ZONE, 0) * 3600) / timeLeftSec;
+
+// Create output
+const fill = status === "Ok" ? "green" : status === "Alarm" ? "red" : "yellow";
+node.status({ fill, shape: "dot", text: "Working" });
+
+const RESOLUTION = 1000;
+
+const payload = {
+  status, // Ok, Warning, Alarm
+  statusOk: status === "Ok",
+  statusWarning: status === "Warning",
+  statusAlarm: status === "Alarm",
+  alarmLevel,
+  highestPerDay,
+  highestCounting,
+  highestCountingWithCurrent,
+  highestToday,
+  currentMonthlyEstimate: Math.round(currentMonthlyEstimate * RESOLUTION) / RESOLUTION,
+  accumulatedConsumptionLastHour: Math.round(accumulatedConsumptionLastHour * RESOLUTION) / RESOLUTION,
+  consumptionLeft: Math.round(consumptionLeft * RESOLUTION) / RESOLUTION,
+  hourEstimate: Math.round(hourEstimate * RESOLUTION) / RESOLUTION,
+  averageConsumptionNow: Math.round(averageConsumptionNow * RESOLUTION) / RESOLUTION,
+  reductionRequired: Math.round(reductionRequired * RESOLUTION) / RESOLUTION,
+  reductionRecommended: Math.round(reductionRecommended * RESOLUTION) / RESOLUTION,
+  increasePossible: Math.round(increasePossible * RESOLUTION) / RESOLUTION,
+  currentStep,
+  currentHourRanking,
+  timeLeftSec,
+  periodMs,
+  accumulatedConsumption,
+};
+
+msg.payload = payload;
+
+return msg;
+```
+
+  </CodeGroupItem>
+</CodeGroup>
+
+:::
+
+### Reduction Actions
+
+This is where you set up actions to be taken in case reduction is required or recommended.
+
+::: danger Configure actions
+You must set up your own actions in this script, if you are going to use actions.
+:::
+
+In the **On Start** tab of this node, you set up the actions by writing a Javascript array,
+the `actions` array.
+The example shows some actions, but you may set up any number of actions.
+
+Actions are taken by sending a payload to a HA `call service` node (the `Perform action` node).
+The items in the `actions` array contains the payload you need to send to the `call service` node
+in order to take action, and the payload you need to send to the same `call service` node
+in order to reset the action.
+
+An action may be to turn on or off a switch, to perform a climate control or what ever else
+you can do to control your entities.
+
+In order to know how much power that is saved by turning off an action, each item must have a sensor
+to give this information. This way, if a device is not using any power, the action will not be taken.
+
+::: warning Entity consumption
+In the current example, there must be a sensor holding the consumption of the entity to
+turn off. If this is not possible, the code must be changed in order to work.
+:::
+
+Each item in the `actions` array contains the following data:
+
+| Variable name         | Description                                                                                                                                                                                                                               |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| consumption           | The consumption that will be reduced by taking the action, given as either a) (Recommended) The entity_id of a sensor that gives the consumption, or b) A number with the consumption in kWh, or c) a function returning the consumption. |
+| name                  | The name of the actions. Can be any thing.                                                                                                                                                                                                |
+| id                    | A unique id of the action.                                                                                                                                                                                                                |
+| minAlarmLevel         | The minimum alarm level that must be present to take this action.                                                                                                                                                                         |
+| reduceWhenRecommended | If `true` the action will be taken when `Reduction Recommended` > 0. If `false` the action will be taken only when `Reduction Required` > 0                                                                                               |
+| minTimeOffSec         | The action will not be reset until minimum this number of seconds has passed since the action was taken.                                                                                                                                  |
+| payloadToTakeAction   | The payload that shall be sent to the `call service` node to take the action (for example turn off a switch).                                                                                                                             |
+| payloadToResetAction  | The payload that shall be sent to the `call service` node to reset the action (for example turn a switch back on again).                                                                                                                  |
+
+::: tip Actions order
+Actions to reduce consumption are taken in the order they appear in the `actions` array until enough reduction has been done,
+so put first the actions you want to take first, and last those actions that you want to take only when really necessary.
+:::
+
+Here is an example of an `actions` array with two items (a water heater and a heating cable):
+
+::: danger On Start code
+Please note that there is a small piece of code after the `actions` array
+in the `On Start` tab. Make sure you do not delete that code.
+:::
+
+::: tip Sensors without actions
+If you don't want the actions, or you want to control actions another way,
+you can omit the action-related nodes and only use the nodes creating the sensors.
+:::
+
+::: details Code
+
+<CodeGroup>
+  <CodeGroupItem title="On Start">
+
+```js
+// You MUST edit the actions array with your own actions.
+
+const actions = [
+  {
+    consumption: "sensor.varmtvannsbereder_electric_consumption_w",
+    name: "Varmtvannsbereder",
+    id: "vvb",
+    minAlarmLevel: 3,
+    reduceWhenRecommended: true,
+    minTimeOffSec: 300,
+    payloadToTakeAction: {
+      domain: "switch",
+      service: "turn_off",
+      target: {
+        entity_id: ["switch.varmtvannsbereder"],
+      },
+    },
+    payloadToResetAction: {
+      domain: "switch",
+      service: "turn_on",
+      target: {
+        entity_id: ["switch.varmtvannsbereder"],
+      },
+    },
+  },
+  {
+    consumption: "sensor.varme_gulv_bad_electric_consumption_w_2",
+    name: "Varme gulv bad 1. etg.",
+    id: "gulvbad",
+    minAlarmLevel: 3,
+    reduceWhenRecommended: true,
+    minTimeOffSec: 300,
+    payloadToTakeAction: {
+      domain: "climate",
+      service: "turn_off",
+      target: {
+        entity_id: ["climate.varme_gulv_bad_2"],
+      },
+    },
+    payloadToResetAction: {
+      domain: "climate",
+      service: "turn_on",
+      target: {
+        entity_id: ["climate.varme_gulv_bad_2"],
+      },
+    },
+  },
+  {
+    consumption: "sensor.varme_gulv_gang_electric_consumption_w",
+    name: "Varme gulv gang 1. etg.",
+    id: "gulvgang",
+    minAlarmLevel: 3,
+    reduceWhenRecommended: true,
+    minTimeOffSec: 300,
+    payloadToTakeAction: {
+      domain: "climate",
+      service: "turn_off",
+      target: {
+        entity_id: ["climate.varme_gulv_gang"],
+      },
+    },
+    payloadToResetAction: {
+      domain: "climate",
+      service: "turn_on",
+      target: {
+        entity_id: ["climate.varme_gulv_gang"],
+      },
+    },
+  },
+  {
+    consumption: "sensor.varme_gulv_kjellerstue_electric_consumption_w",
+    name: "Varme gulv kjellerstue",
+    id: "gulvkjeller",
+    minAlarmLevel: 3,
+    reduceWhenRecommended: true,
+    minTimeOffSec: 300,
+    payloadToTakeAction: {
+      domain: "climate",
+      service: "turn_off",
+      target: {
+        entity_id: ["climate.varme_gulv_kjellerstue"],
+      },
+    },
+    payloadToResetAction: {
+      domain: "climate",
+      service: "turn_on",
+      target: {
+        entity_id: ["climate.varme_gulv_kjellerstue"],
+      },
+    },
+  },
+  {
+    consumption: 0.1,
+    name: "Test",
+    id: "test",
+    minAlarmLevel: 3,
+    reduceWhenRecommended: true,
+    minTimeOffSec: 30,
+    payloadToTakeAction: {
+      domain: "switch",
+      service: "turn_off",
+      target: {
+        entity_id: ["switch.lys_kjokkenskap_switch"],
+      },
+    },
+    payloadToResetAction: {
+      domain: "switch",
+      service: "turn_on",
+      target: {
+        entity_id: ["switch.lys_kjokkenskap_switch"],
+      },
+    },
+  },
+];
+// End of actions array
+
+// DO NOT DELETE THE CODE BELOW
+
+// Set default values for all actions
+actions.forEach((a) => {
+  a.actionTaken = false;
+  a.savedConsumption = 0;
+});
+
+flow.set("actions", actions);
+```
+
+  </CodeGroupItem>
+
+  <CodeGroupItem title="On Message" active>
+
+```js
+const MIN_CONSUMPTION_TO_CARE = 0.05; // Do not reduce unless at least 50W
+
+const actions = flow.get("actions");
+const ha = global.get("homeassistant").homeAssistant;
+
+let reductionRequired = msg.payload.reductionRequired;
+let reductionRecommended = msg.payload.reductionRecommended;
+
+if (reductionRecommended <= 0) {
+  return null;
+}
+
+function takeAction(action, consumption) {
+  const info = {
+    time: new Date().toISOString(),
+    name: "Reduction action",
+    data: msg.payload,
+    action,
+  };
+  node.send([{ payload: action.payloadToTakeAction }, { payload: info }]);
+  reductionRequired = Math.max(0, reductionRequired - consumption);
+  reductionRecommended = Math.max(0, reductionRecommended - consumption);
+  action.actionTaken = true;
+  action.actionTime = Date.now();
+  action.savedConsumption = consumption;
+  flow.set("actions", actions);
+}
 
-This is where numbers are evaluated to figure out if the current hour is in risk of breaching the limit for the next step.
-The output is as follows:
+function getConsumption(consumption) {
+  if (typeof consumption === "string") {
+    const sensor = ha.states[consumption];
+    return sensor.state;
+  } else if (typeof consumption === "number") {
+    return consumption;
+  } else if (typeof consumption === "function") {
+    return consumption();
+  } else {
+    node.warn("Config error: consumption has illegal type: " + typeof consumption);
+    return 0;
+  }
+}
 
-| Name                   | Description                                                                         |
-| ---------------------- | ----------------------------------------------------------------------------------- |
-| status                 | The status of the current hour (Ok, Warning or Alarm).                              |
-| highestPerDay          | An array with the worst hour for each day this month                                |
-| highestCounting        | An array with the 3 worst days this month, including passed hours today.            |
-| highestToday           | The worst hour until now today, not including current hour.                         |
-| currentMonthlyEstimate | The average of the three worst days, including this hour.                           |
-| hourEstimate           | The estimate for the current hour.                                                  |
-| currentStep            | The upper limit of the step we are currently on.                                    |
-| currentHourRanking     | The rank of the current hour, from 1 to 4, where 4 is the lowest                    |
-| reductionRequired      | The power that must be reduced the rest of the hour in order to not break the limit |
+actions
+  .filter((a) => msg.payload.alarmLevel >= a.minAlarmLevel && !a.actionTaken)
+  .forEach((a) => {
+    const consumption = getConsumption(a.consumption);
+    if (consumption < MIN_CONSUMPTION_TO_CARE) {
+      return;
+    }
+    if (reductionRequired > 0 || (reductionRecommended > 0 && a.reduceWhenRecommended)) {
+      takeAction(a, consumption);
+    }
+  });
+```
 
-## Actions
+  </CodeGroupItem>
+</CodeGroup>
 
-You may set up actions to be taken when the status is Warning or Alarm.
-For each action, specify priority and expected reduction in kW,
-as well as what data to send as output for that action.
+:::
 
-When a warning or an alarm has been on for a specified time, actions are taken.
-Actions are taken in prioritized order, until enough reduction is expected,
-so multiple actions may be taken at the same time.
+### Reset Actions
 
-Actions are defined in an array in the beginning of the script.
-The first action has highest priority, that is it will be executed first.
-The rest follow in prioritized order.
+This node will reset actions when there is enough capacity available, that is for example turning switches back on again.
 
-For each action, the following is specified:
+In the script, there is a `BUFFER_TO_RESET` constant used to set a buffer (in kW) so actions are not reset until there is
+some spare capacity. By default is it set to 1 kW.
 
-- sensor - The the entity id of the sensor that gives you the effect that will be reduced.
-- outputActivate - The data sent to the output to acticate the action.
-- outputDeactivate - The data sent to the output to deactivate the action.
-- activateOnWarning - true if this shall be activated on warning.
+::: details Code
 
-The node has the same number of outputs as there are actions.
-The first output is for the first action, and so on.
-When an action is activated, the outputActivate data is sent to the corresponding output.
-When the hour is over, the action is deactivated.
-When an action is deativated, the outputDeactivate data is sent to the corresponding output.
+<CodeGroup>
+  <CodeGroupItem title="On Message" active>
 
-It is up to you to define how to use the actions.
+```js
+const actions = flow.get("actions");
+const ha = global.get("homeassistant").homeAssistant;
 
-# TO DO
+const BUFFER_TO_RESET = 1; // Must have 1kW extra to perform reset
+
+let increasePossible = msg.payload.increasePossible;
+
+if (increasePossible <= 0) {
+  return null;
+}
+
+function resetAction(action) {
+  const info = {
+    time: new Date().toISOString(),
+    name: "Reset action",
+    data: msg.paylaod,
+    action,
+  };
+  node.send([{ payload: action.payloadToResetAction }, { payload: info }]);
+  increasePossible -= action.savedConsumption;
+  action.actionTaken = false;
+  action.savedConsumption = 0;
+  flow.set("actions", actions);
+}
+
+actions
+  .filter(
+    (a) =>
+      a.actionTaken &&
+      a.savedConsumption + BUFFER_TO_RESET <= increasePossible &&
+      Date.now() - a.actionTime > a.minTimeOffSec * 1000
+  )
+  .forEach((a) => resetAction(a));
+```
 
-- Implement actions
-- Make a safety margin in kW so we reduce a little more than necessary.
-- May need some kind of warning when hourEstimate > currentStep, even if currentMonthlyEstimate is not.
-- Maybe set reductionRequired to hourEstimate - currentStep in this case.
+  </CodeGroupItem>
+</CodeGroup>
+
+:::
+
+### Perform action
+
+This is a `call service` node used to perform the actions (both taking actions and resetting actions).
+There is no setup here except selecting the HA server.
+
+### Save actions to file
+
+Saves some information to a file, when actions are taken or reset. This is just so you can watch what has been done.
+Please make sure the file name configured works for you (for example that the folder exists in your HA instance).
+
+### Catch action errors
+
+This is supposed to catch any errors in the action-related nodes, and log them to the file.
+
+### Entity nodes
+
+There is a large number of `entity` nodes, one for each sensor value that is created with values from the `Calculate values` node.
+See [Calculated sensor values](#calculated-sensor-values) for description of each sensor value.
+
+## The code
+
+Below is the code for the Node-RED flow.
+Copy the code and paste it to Node-RED using Import in the NR menu.
+
+::: details Flow code
+@[code](./example-grid-tariff-capacity-flow.json)
+:::