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

package/docs/faq/README.md

@@ -47,4 +47,4 @@ Another alternative is to reduce the minimum saving from 0.05 to 0.001. Then the
 
 ## Can we get Legionella bacteria when turning off the water heater?
 
-Many people ask if there is a danger that legionella bacteria will grow and become dangerous when the temperature of the water heater is lowered. As long as the water is heated to at least 65 °C every day, or at least every week, the risk of infection is not considered significant, according to the norwegian [FHI](https://www.fhi.no/nettpub/legionellaveilederen/).
+Be aware that the norwegian [FHI](https://www.fhi.no/nettpub/legionellaveilederen/) recommends that the temperature in the water heater is at least 70°C to avoid growth of legionella. At this temperature, legionalla bacteria die quickly.

package/docs/faq/best-save-viewer.md

@@ -55,7 +55,7 @@ If the number is black, it could be used, but only if all other criteria are sat
 
 ## Something seems wrong
 
-The tool is not using the same code as the node, so in case there is a bg in the node (or in the tool) the numbers may not match.
+The tool is not using the same code as the node, so in case there is a bug in the node (or in the tool) the numbers may not match.
 
 <hr/>
 

package/docs/guide/README.md

@@ -9,7 +9,7 @@ sidebar: "auto"
 This is a collection of nodes for the popular [Node-RED](https://nodered.org/) that you can use to save money on variable electricity prices. Node-RED is a widely used low-code programming tool that can be used together with many smart home solutions to create automations.
 
 The solution can be used to control switches or other entities in a smart home system, and for example turn on when the price is low, and turn off when the price is high.
-There are different ways to calculate what hours to turn on and off, and these are implemented as **strategies nodes**. Each strategy node can be configured to fit different purposes.
+There are different ways to calculate what hours to turn on and off, and these are implemented as **strategy nodes**. Each strategy node can be configured to fit different purposes.
 
 The strategies need price data to work. These can be received from different sources, for example Tibber, Nord Pool or custom sources.
 
@@ -41,7 +41,7 @@ May also be installed via npm:
 
 `npm install node-red-contrib-power-saver`
 
-Make sure that you upgrade now and then to get the latest version. See [changelog](CHANGELOG) for changes.
+Make sure that you upgrade now and then to get the latest version. See [changelog](../changelog/README.md) for changes.
 
 ### Get price data
 
@@ -175,9 +175,9 @@ Use the outputs to control switches, thermostats or other entities to control yo
 
 The following os valid for the Best Save and Lowest Price strategies:
 
-**Output 1** is used to turn on. A payload with value `true` is sent every time turning on is scheduled.
+**Output 1** is used to turn on. A payload with value `true` (or another configured value) is sent every time turning on is scheduled.
 
-**Output 2** is used to turn off. A payload with value `false` is sent every time turning off is scheduled.
+**Output 2** is used to turn off. A payload with value `false` (or another configured value) is sent every time turning off is scheduled.
 
 Example using Home Assistant:
 
@@ -198,14 +198,29 @@ There are many ways you can use the output:
 
 For users of Magic Mirror and Tibber, the `ps-best-save` node can send its schedule to the MMM-Tibber module. See more details in the `ps-best-save` node documentation.
 
+### Combine schedules
+
+With the Schedule Merger node, you can combine multiple schedules in order to get more control of the result.
+You can combine the schedule output from Best Save or Lowest Price nodes using logical `OR`or `AND` algorithms.
+Here is an example:
+
+![Schedule Merger Example](../images/schedule-merger-example-1.png)
+
+In this example, the result of two Lowest Price nodes and one Best Save node are combined in a Schedule Merger node, resulting in one schedule. The output from the Schedule Merger node is used to control a switch.
+
+Se the [Schedule Merger](../nodes/ps-schedule-merger.md) node for more details.
+
 ### More information
 
 There are more details and more information in the documentation for each [node](/nodes/) and in the [examples](/examples/).
 
 ## Migration from v2
 
-The `Power Saver` node from v2 is still here, and it is working exactly as before. However, it will not be further maintained, so you should replace it. You may directly replace the `Power Saver` node by two of the new nodes:
+The `Power Saver` node from v2 has been removed and must be replaced.
+You may directly replace the `Power Saver` node by two of the new nodes (`ps-receive-price` and `ps-strategy-best-save`):
 
 ![Migrate Power Saver](../images/migrate-best-save.png)
 
 See more details in the [documentation for the `ps-strategy-best-save`](../nodes/ps-strategy-best-save.md) node.
+
+<VippsPlakat/>

package/docs/nodes/README.md

@@ -2,12 +2,6 @@
 
 Here is an overview of the nodes, and links to detailed descriptions for eah of them.
 
-## [Power Saver](./power-saver) <Badge type="warning" text="deprecated" vertical="middle" />
-
-![Power Saver node](../images/node-power-saver.png)
-
-The old node from version 2 is still working, but should be replaced.
-
 ## Strategy nodes
 
 These are the nodes used to calculate and control saving.
@@ -30,6 +24,12 @@ Strategy to find the x hours with lowest price in a given period each day.
 
 A strategy for moving consumption from expensive to cheap periods utilizing climate entities and trading principles.
 
+### [ps-strategy-fixed-schedule](./ps-strategy-fixed-schedule)
+
+![ps-strategy-fixed-schedule](../images/node-ps-strategy-fixed-schedule.png)
+
+A strategy for setting a fixed daily or weekly schedule.
+
 ## Utility nodes
 
 ### [ps-receive-price](./ps-receive-price)
@@ -38,6 +38,12 @@ A strategy for moving consumption from expensive to cheap periods utilizing clim
 
 Node to convert different types of input data to the format used by the strategy nodes.
 
+### [ps-schedule-merger](./ps-schedule-merger)
+
+![ps-schedule-merger](../images/node-ps-schedule-merger.png)
+
+Node to combine multiple schedules into one schedule.
+
 ## Grid tariff nodes
 
 ### [ps-general-add-tariff](./ps-general-add-tariff)

package/docs/nodes/dynamic-commands.md

@@ -0,0 +1,79 @@
+# Dynamic commands
+
+You can dynamically send some commands to the node via its input, by using a `commands` object in the payload as described below.
+This applies to the following nodes:
+
+- Best Save
+- Lowest Price
+- Schedule Merger
+
+Commands can be sent together with config or price data. You can command multiple commands in one message, but then put them all in the same commands-object.
+
+## Commands
+
+### sendSchedule
+
+You can get the schedule sent to output 3 any time by sending a message like this to the node:
+
+```json
+"payload": {
+  "commands": {
+    "sendSchedule": true,
+  }
+}
+```
+
+When you do this, the current schedule is actually recalculated based on the last received data, and then sent to output 3 the same way as when it was originally planned.
+
+### sendOutput
+
+You can get the node to send the current output to output 1 or 2 any time by sending a message like this to the node:
+
+```json
+"payload": {
+  "commands": {
+    "sendOutput": true,
+  }
+}
+```
+
+When you do this, the current schedule is actually recalculated based on the last received data. The current output is sent to output 1 or 2.
+
+### reset
+
+You can reset data the node has saved in context by sending this message:
+
+```json
+"payload": {
+  "commands": {
+    "reset": true,
+  }
+}
+```
+
+When you do this, all historical data the node has saved is deleted, including the current schedule, so the result will be
+that the node shows status "No price data". When new price data is received, a schedule is calculated without considering any history.
+
+The nodes config is not deleted, as the node depends on it to work.
+
+::: warning
+This operation cannot be undone.
+
+However, it is normally not a big loss, as you can just feed the node with new price data and start from scratch.
+:::
+
+### replan
+
+By sending this command, you can have the node read the last received prices from the context storage,
+and make a plan based on those prices:
+
+```json
+"payload": {
+  "commands": {
+    "replan": true,
+  }
+}
+```
+
+If the context storage is `file` you can use this to create a new schedule after a restart,
+instead of fetching prices again.

package/docs/nodes/dynamic-config.md

@@ -0,0 +1,76 @@
+# Dynamic config
+
+It is possible to change config dynamically by sending a config message to the node.
+This applies to the following nodes:
+
+- Best Save
+- Lowest Price
+- Heat Capacitor
+- Schedule Merger
+
+Dynamic config is sent on the input as a message with a payload containing a `config` object and optionally a `name`.
+Example:
+
+```json
+"payload": {
+  "name": "Best Save",
+  "config": {
+    "maxHoursToSaveInSequence": 4,
+    "minSaving": 0.02
+  }
+}
+```
+
+See documentation for each specific node for which values that can be sent.
+All the variables in the config object are optional. You should send only those you want to change.
+
+::: tip name
+If `name` is used, it must match the nodes name in order to have effect. Normally you do not use `name`.
+The main intention of `name` is for the [grid capacity example](../examples/example-grid-tariff-capacity-part.md)
+to be able to override a specific strategy node.
+The `name` is the exact same value as you set as name in the nodes config.
+:::
+
+## Output values
+
+Valid values for `outputValueForOntype` and `outputValueForOfftype` are `bool`, `num` and `str` and must correspond
+with the values for `outputValueForOn` and `outputValueForOff`. Also `str` values must be enclosed by quotes, for example:
+`"outputValueForOn": "myvalue"`, while `num` and `bool` values shall not, for example: `"outputValueForOn": 1`.
+
+The config sent like this will be valid until a new config is sent the same way, or until the flow is restarted. On a restart, the original config set up in the node will be used.
+
+When a config is sent like this, and without price data, the schedule will be replanned based on the last previously received price data. If no price data has been received, no scheduling is done.
+
+However, you can send config and price data in the same message. Then both will be used.
+
+## Override
+
+It is possible to send an override message to a strategy node (Best Save or Lowest Price) and to the Schedule Merger node.
+An override message looks like this:
+
+```json
+"payload": {
+  "name": "Best Save",
+  "config": {
+    "override": "off"
+  }
+}
+```
+
+`name` is optional and is only necessary when you send the message to multiple nodes, but want it to have effect only on
+nodes with the given name.
+
+Legal values for override are:
+
+| Value    | Function                                                                                 |
+| -------- | ---------------------------------------------------------------------------------------- |
+| `"on"`   | The node will only send output `on`                                                      |
+| `"off"`  | The node will only send output `off`                                                     |
+| `"auto"` | The node will work according to the schedule. This is the standard and the default mode. |
+
+## Config saved in context
+
+The nodes config is saved in the nodes context.
+If dynamic config is sent as input, this replaces the saved config.
+It is the config that is saved in context that is used when calculating.
+When Node-RED starts or the flow is redeployed, the config defined in the node replaces the saved config and will be used when planning.

package/docs/nodes/ps-elvia-add-tariff.md

@@ -1,3 +1,7 @@
+---
+prev: ./ps-general-add-tariff.md
+---
+
 # ps-elvia-add-tariff
 
 ![ps-elvia-add-tariff](../images/node-ps-elvia-add-tariff.png)

package/docs/nodes/ps-general-add-tariff.md

@@ -1,3 +1,8 @@
+---
+prev: ./ps-schedule-merger.md
+next: ./ps-elvia-add-tariff.md
+---
+
 # ps-general-add-tariff
 
 ![ps-general-add-tariff](../images/node-ps-general-add-tariff.png)
@@ -35,6 +40,11 @@ You can have from 1 to 24 periods during the day, with different values to add f
 
 For each period, select the time of the day the value is valid from, and enter the value.
 
+::: danger Price unit
+Be careful to use the correct unit when entering the price here. If the price is `28 øre` enter `0.28`.
+If the price is `36 cents` enter `0.36`.
+:::
+
 ### Days
 
 Check which days the price is valid for. For the price to be added, both the time and the day must be correct.

package/docs/nodes/ps-receive-price.md

@@ -1,5 +1,6 @@
 ---
-prev: ./ps-strategy-lowest-price.md
+prev: ./ps-strategy-heat-capacitor.md
+next: ./ps-schedule-merger.md
 ---
 
 # ps-receive-price

package/docs/nodes/ps-schedule-merger.md

@@ -0,0 +1,227 @@
+---
+prev: ./ps-receive-price.md
+next: ./ps-general-add-tariff.md
+---
+
+# ps-schedule-merger
+
+![ps-schedule-merger](../images/node-ps-schedule-merger.png)
+
+## Description
+
+This node can be used to merge schedules from multiple strategy nodes, and create one resulting schedule. It can be useful for example to have multiple lowest price nodes to cover different periods of the day. Send all schedules as input to this node and get one schedule as output. It works for schedules from Lowest Price, Best Save and Fixed Schedule.
+
+![Schedule Merger Example](../images/schedule-merger-example-1.png)
+
+All incoming schedules are saved, and after a timeout, a new resulting schedule is calculated based on all incoming schedules. The timeout can be configured, and should be long enough for all preceding strategy nodes to finish their calculation. Normally all strategy nodes will receive the same set of prices at the same time, and do their calculations almost simultaneously, so all strategies can send their schedules at the same time.
+
+The schedules that are merged must be for the exact same period and have the exact same number of hours. If only one schedule is received, it is used unchanged.
+
+::: warning Different period
+If a schedule with prices for a different period is received, all saved schedules are deleted, and not used any more.
+:::
+
+The merge can be done using one of two functions:
+
+- OR
+- AND
+
+### OR
+
+For each hour, all schedules are compared. If any of them is `on`, the hour in the resulting schedule is `on`.
+Only if all schedules has the hour set to `off` will the resulting schedule have the hour `off`.
+
+### AND
+
+For each hour, all schedules are compared. If any of them is `off`, the hour in the resulting schedule is `off`.
+Only if all schedules has the hour set to `on` will the resulting schedule have the hour `on``.
+
+::: tip Combine with Fixed Schedule
+Use the Fixed Schedule strategy node to create a mask for a period of the day when you want to make
+sure the switch is turned on or off, and then merge the schedule from the Fixed Schedule strategy with
+the schedule from for example the Lowest Price node, using the Schedule Merger node.
+:::
+
+## Configuration
+
+![Schedule Merger Config](../images/schedule-merger-config.png)
+
+| Value                  | Description                                                                                                                                                                                    |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Function               | Merging function, either OR or AND (see above).                                                                                                                                                |
+| Delay                  | Delay in milliseconds from a schedule is received until a new schedule is calculated. Use this so all schedules can be received before a new schedule is calculated and used.                  |
+| Output value for on    | Set what value to output on output 1 in order to turn on. Default is `boolean true`. You can also select a `number`, for example `1`, or a `string`, for example `on`, or any other value.     |
+| Output value for off   | Set what value to output on output 2 in order to turn off. Default is `boolean false`. You can also select a `number`, for example `0`, or a `string`, for example `off`, or any other value.  |
+| Send when rescheduling | Check this to make sure on or off output is sent immediately after rescheduling. If unchecked, the output is sent only if it has not been sent before, or is different from the current value. |
+| If no schedule, send   | What to do if there is no valid schedule any more (turn on or off). This value will be sent also before there is any valid schedule, or after the last hour there is price data for.           |
+
+### Dynamic config
+
+The following config values can be changed dynamically:
+
+| Name                               | Description                                              |
+| ---------------------------------- | -------------------------------------------------------- |
+| `logicFunction`                    | Legal values: `"OR"`, `"AND"`                            |
+| `schedulingDelay`                  | Number (milliseconds), example: `2000`                   |
+| `outputIfNoSchedule`               | Legal values: `true`, `false`                            |
+| `sendCurrentValueWhenRescheduling` | Legal values: `true`, `false`                            |
+| `outputValueForOn`                 | See description in [Dynamic Config](./dynamic-config.md) |
+| `outputValueForOff`                | See description in [Dynamic Config](./dynamic-config.md) |
+| `outputValueForOntype`             | See description in [Dynamic Config](./dynamic-config.md) |
+| `outputValueForOfftype`            | See description in [Dynamic Config](./dynamic-config.md) |
+| `override`                         | Legal values: `"on"`, `"off"`, `"auto"`                  |
+
+See [Dynamic Config](./dynamic-config.md) for details and how to send dynamic config.
+
+### Dynamic commands
+
+You can send dynamic commands to this node, for example to make it resend output.
+See [Dynamic Commands](./dynamic-commands.md) for details and how to send dynamic commands.
+
+## Input
+
+Input is the same as the output from the Lowest Price node and the Best Save node, but only the `hours` array is used.
+
+You can make your own input by supplying a payload containing an hours array. Example:
+
+```json
+{
+  "hours": [
+    {
+      "price": 1.2584,
+      "onOff": false,
+      "start": "2021-09-30T00:00:00.000+02:00",
+      "saving": 0.2034
+    },
+    {
+      "price": 1.055,
+      "onOff": true,
+      "start": "2021-09-30T01:00:00.000+02:00",
+      "saving": null
+    },
+    {
+      "price": 1.2054,
+      "onOff": true,
+      "start": "2021-09-30T02:00:00.000+02:00",
+      "saving": null
+    }
+  ]
+}
+```
+
+## Output
+
+There are three outputs. You use only those you need for your purpose.
+
+### Output 1
+
+A payload with the value set in config, default `true`, is sent to output 1 whenever the power / switch shall be turned on.
+
+### Output 2
+
+A payload with the value set in config, default `false`, is sent to output 2 whenever the power / switch shall be turned off.
+
+### Output 3
+
+When valid input is received, and the schedule is recalculated (after the timeout), the resulting schedule, as well as some other information, is sent to output 3. You can use this to see the plan and verify that it meets your expectations. You can also use it to display the schedule in any way you like.
+
+Example of output:
+
+```json
+{
+  "schedule": [
+    { "time": "2022-10-31T00:00:00.000+01:00", "value": true, "countHours": 5 },
+    { "time": "2022-10-31T05:00:00.000+01:00", "value": false, "countHours": 1 },
+    { "time": "2022-10-31T06:00:00.000+01:00", "value": true, "countHours": 3 },
+    { "time": "2022-10-31T09:00:00.000+01:00", "value": false, "countHours": 2 },
+    { "time": "2022-10-31T11:00:00.000+01:00", "value": true, "countHours": 21 },
+    { "time": "2022-11-01T08:00:00.000+01:00", "value": false, "countHours": 3 },
+    { "time": "2022-11-01T11:00:00.000+01:00", "value": true, "countHours": 3 },
+    { "time": "2022-11-01T14:00:00.000+01:00", "value": false, "countHours": 3 },
+    { "time": "2022-11-01T17:00:00.000+01:00", "value": true, "countHours": 7 },
+    { "time": "2022-11-02T00:00:00.000+01:00", "value": false, "countHours": null }
+  ],
+  "hours": [
+    {
+      "start": "2022-10-31T00:00:00.000+01:00",
+      "onOff": true,
+      "sources": {
+        "01e61b1bc2b094e5": {
+          "hour": { "start": "2022-10-31T00:00:00.000+01:00", "price": 0.5197, "onOff": false, "saving": null }
+        },
+        "7c8126f3a95f9cc0": {
+          "hour": { "start": "2022-10-31T00:00:00.000+01:00", "price": 0.5197, "onOff": true, "saving": null }
+        },
+        "e4ded64403d92b14": {
+          "hour": { "start": "2022-10-31T00:00:00.000+01:00", "price": 0.5197, "onOff": false, "saving": null }
+        }
+      },
+      "price": 0.5197,
+      "saving": null
+    },
+    {
+      "start": "2022-10-31T01:00:00.000+01:00",
+      "onOff": true,
+      "sources": {
+        "01e61b1bc2b094e5": {
+          "hour": { "start": "2022-10-31T01:00:00.000+01:00", "price": 0.5117, "onOff": false, "saving": null }
+        },
+        "7c8126f3a95f9cc0": {
+          "hour": { "start": "2022-10-31T01:00:00.000+01:00", "price": 0.5117, "onOff": true, "saving": null }
+        },
+        "e4ded64403d92b14": {
+          "hour": { "start": "2022-10-31T01:00:00.000+01:00", "price": 0.5117, "onOff": true, "saving": null }
+        }
+      },
+      "price": 0.5117,
+      "saving": null
+    },
+    // ...
+    {
+      "start": "2022-11-01T23:00:00.000+01:00",
+      "onOff": true,
+      "sources": {
+        "01e61b1bc2b094e5": {
+          "hour": { "start": "2022-11-01T23:00:00.000+01:00", "price": 0.2233, "onOff": true, "saving": null }
+        },
+        "7c8126f3a95f9cc0": {
+          "hour": { "start": "2022-11-01T23:00:00.000+01:00", "price": 0.2233, "onOff": true, "saving": null }
+        },
+        "e4ded64403d92b14": {
+          "hour": { "start": "2022-11-01T23:00:00.000+01:00", "price": 0.2233, "onOff": false, "saving": null }
+        }
+      },
+      "price": 0.2233,
+      "saving": null
+    }
+  ],
+  "source": "Schedule Merger",
+  "config": {
+    "logicFunction": "OR",
+    "schedulingDelay": "2000",
+    "outputIfNoSchedule": false,
+    "hasChanged": false
+  },
+  "time": "2022-10-31T21:56:51.178+01:00",
+  "version": "4.0.0",
+  "strategyNodeId": "796f2d96a83aa709",
+  "current": true
+}
+```
+
+The `schedule` array shows every time the switch is turned on or off. The `hours` array shows values per hour containing the price (received as input), whether that hour is on or off and the start time of the hour. The `saving` value is always `null`.
+
+## Usage ideas
+
+### Multiple Lowest Price
+
+If you want a switch to be on for example two of the cheapest hours between 00:00 and 08:00, and then the two cheapest hours between 12:00 and 20:00, you can do this by combining the schedule from two Lowest Price nodes, one for each of the mentioned periods. Merge the two using a Schedule Merger node with the `OR` function. Make sure to send `off` if no schedule for all nodes.
+
+### Day-filter for strategy nodes
+
+If you have a strategy node, for example Lowest Price or Best Save, that you want to have effect only on weekdays,
+make a Fixed Schedule node with all hours on, but only valid for weekdays, then merge the two of them with
+the Schedule Merger function `"AND"`. Make sure the `If no schedule, send` is set to `off` so that this will be the
+values for the other days.
+
+<VippsPlakat/>