node-red-contrib-power-saver 2.1.0 → 3.0.3

package/docs/guide/README.md

@@ -0,0 +1,202 @@
+---
+sidebar: "auto"
+---
+
+# Guide
+
+## Introduction
+
+This is a collection of nodes you can use to save money on variable power prices. 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 impemented as **strategies nodes**. Each stragety 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.
+
+::: warning Price sources
+Tibber and Nord Pool are only available in the nordics, so if you live outside the nordics, you must find another source of price data, and make your own input.
+:::
+
+Grid tariff is normally not part of the electricity price, so if this varies by the hour, it must be added before sent to the strategy nodes for calculation. This can be done by putting a `ps-xxx-add-tariff` node between the price receiver and the strategy.
+
+The strategy nodes have 3 outputs. Output 1 is used to "turn on", output 2 is used to "turn off", and on output 3, the calculated schedule and some other information is sent. You can use this to make graphs, or just send it to a debug node to view it.
+
+Example:
+
+![Example flow](../images/example-flow-1.png)
+
+Here prices are received from Tibber, converted in the `ps-receive-price` node, then gridd tariff for Elvia is added before sent to the `ps-strategy-best-save` node. Output is sent to Home Assistant via two `call-service` nodes, and the schedule is sent to a debug node.
+
+::: tip Home Assistant
+The node collection fits very well with Home Assistant (HA), as Node-RED is frequently used for automations, and there also is an integration with Nord Pool, but there is no direct dependency to HA, so all nodes can be used also without HA.
+:::
+
+## Getting started
+
+### Installation
+
+Install in Node-RED via the Manage Palette menu.
+
+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.
+
+### Get price data
+
+This solution is useless without price data. In the nordics, there are at least two very common places to get price data from:
+
+- Tibber
+- Nord Pool
+
+The `ps-receive-price` node is designed to handle price input frome both these, and convert it to the format required by the strategy nodes.
+
+If you are a Tibber customer, use the `tibber-query` node from the [Tibber API](https://flows.nodered.org/node/node-red-contrib-tibber-api) to receive price, with one of the following queries:
+
+<CodeGroup>
+  <CodeGroupItem title="All homes">
+
+```gql
+{
+  viewer {
+    homes {
+      id
+      address {
+        address1
+        address2
+        address3
+        postalCode
+        city
+        country
+      }
+    }
+  }
+}
+```
+
+  </CodeGroupItem>
+
+  <CodeGroupItem title="Singel home" active>
+
+```gql{3}
+{
+  viewer {
+    home(id: "142c1670-ab43-2ab3-ba6d-723703a551e2") {
+      currentSubscription{
+        priceInfo{
+          today {
+            total
+            energy
+            tax
+            startsAt
+          }
+          tomorrow {
+            total
+            energy
+            tax
+            startsAt
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+  </CodeGroupItem>
+</CodeGroup>
+
+See more details in the [documentation](../nodes/ps-receive-price#tibber-input) for the `ps-receive-price` node.
+
+Se documentation for [node-red-contrib-tibber-api](https://flows.nodered.org/node/node-red-contrib-tibber-api) for details about the Tibber query.
+
+::: tip Tibber query
+You can use an `inject` node (standard Node-RED) to send the Tibber query as a text string int to the `tibber-query` node. This can be set to repeat the query for example every hour.
+:::
+
+[See example of Tibber flow and mqtt](../examples/example-tibber-mqtt.md)
+
+If you use Home Assistant (HA), you can install the
+[Nord Pool custom component](https://github.com/custom-components/nordpool),
+that provides a _sensor_ that gives price per hour for today and tomorrow.
+Data can be sent from both the `current state` node or the `events: state` node.
+
+[See example with Nordpool and `current state` node](../images/example-nordpool-current-state.md)
+
+[See example with Nordpool and `events: state` node](../images/example-nordpool-events-state.md)
+
+### Add grid tariff
+
+When also the grid tariff changes per hour, it must be added to the electricity price in order to get the calculations right.
+
+After the the `ps-receive-price` node, add a `ps-xxx-add-tariff` node to add grid tariff. What node to choose depends on what grid you get electricity through. The followinggrids are supported:
+
+| Grid supplier | Node                  |
+| ------------- | --------------------- |
+| Elvia         | `ps-elvia-add-tariff` |
+
+Oops. Only one grid is currently supported.
+
+If your grid is not supported, you may code this yourself.
+
+::: tip Skip this step
+If the grid tariff is the same the whole day, you can skip this step i the flow.
+:::
+
+### Calculate and run schedule
+
+This is the step where the value is produced. Based on the prices received, the optimal schedule for you is calculated automatically, based on your configuration. You can choose between the following strategies:
+
+| Strategy     | Node                        | Description                                                     |
+| ------------ | --------------------------- | --------------------------------------------------------------- |
+| Best save    | `ps-strategy-best-save`     | Postpone power consumption when there is most to save.          |
+| Lowest price | `ps--strategy-lowest-price` | Turn on power when the prices are the lowest in a given period. |
+
+These nodes must be configured for your purpose. See configuration description and other details in the documentation for each node.
+
+Send the result from the `ps-xxx-add-tariff` node (or the `ps-receive-price` node) as input to the
+strategy node you choose.
+
+::: tip Choose strategy
+Choose the best save strategy if you can postpone power consumption, and expect the consumption to occur during the first hour after power is turned on again.
+
+Choose the lowest price strategy if you need the power to be on for x hours, but it is not important when that is. Note that you can select to have all hours on in one consecutive period, or spread around on the cheapest hours.
+:::
+
+### Use schedule signals
+
+Use the outputs to control switches, thermostats or other entities to control your power consumers.
+
+**Output 1** is used to turn on. A payload with value `true` 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.
+
+Example using Home Assistant:
+
+![Example flow](../images/example-flow-2.png)
+
+::: tip Use output
+There are many ways you can use the output:
+
+- Turn on/off a switch
+- Set a termostat up, down or to specific values
+- Change setting of a dimmer
+- Send a notification
+  :::
+
+### Display schedule
+
+**Output 3** can be used to print or dispay the calculated schedule. If you just want to see it, send it to a debug node. You can also use it to display the result as graphs in HA.
+
+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.
+
+### 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:
+
+![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.

package/docs/nodes/README.md

@@ -0,0 +1,53 @@
+# Nodes
+
+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.
+
+### [ps-strategy-best-save](./ps-strategy-best-save)
+
+![ps-strategy-best-save](../images/node-ps-strategy-best-save.png)
+
+Strategy to find the best hours to turn off for most saving.
+
+### [ps-strategy-lowest-price](./ps-strategy-lowest-price)
+
+![ps-strategy-lowest-price](../images/node-ps-strategy-lowest-price.png)
+
+Strategy to find the x hours with lowest price in a given period each day.
+
+## Utility nodes
+
+### [ps-receive-price](./ps-receive-price)
+
+![ps-receive-price](../images/node-ps-receive-price.png)
+
+Node to convert different types of input data to the format used by the strategy nodes.
+
+## Grid tariff nodes
+
+### [ps-elvia-add-tariff](./ps-elvia-add-tariff)
+
+![ps-elvia-add-tariff](../images/node-ps-elvia-add-tariff.png)
+
+Node to add Elvia grid tariff to the prices before sending them to the strategy nodes.
+
+## Other nodes
+
+These are a couple of other nodes for using the Elvia API, but these are not important to the Power Saver, so they are not given any further documentation here.
+
+### ps-elvia-tariff-types
+
+Use this to get a list of the tariff types available in the Elvia API.
+
+### ps-elvia-tariff
+
+Use this to get the Elvia grid tariff for a selected tariff type.

package/docs/nodes/old-power-saver-doc.md

@@ -0,0 +1,231 @@
+# node-red-contrib-power-saver v2 (deprecated)
+
+A Node-RED node to save money when power prices are changing. Saving is done by postponing power consumption until the price is lower.
+
+You can configure maximum number of hours to save in a sequence, and minimum time to recover after a maximum saving period.
+
+![Normal flow](https://github.com/ottopaulsen/node-red-contrib-power-saver/blob/main/doc/node-red-contrib-power-saver-flow.png?raw=true)
+
+You can use it to control for example a heater, a water heater or any other power consumer that is acceptable to turn off now and then.
+
+The node takes power prices per hour as input, and sends output to turn a switch on or off based on the power price. It also outputs the schedule that is planned, as well as how much you save per kWh for each of the hours that are turned off, assuming that the same power is used as soon as the power is turned on.
+
+Power prices may be received from Tibber, Nordpool or any other source that gives price per hour for today and optionally tomorrow. It is primarily made to be used together with Home Assistant (HA), but there is no dependency to HA, so it can just as well be used by itself.
+
+The node can also be used in combination with MagicMirror with the MMM-MQTT and MMM-Tibber modules, in order to get the savings displayed on the MM screen in the MMM-Tibber module.
+
+**NB! WIP**
+
+This node is currently rather new, and has been tried for a few weeks, enough to come in a version two with improved savings plan.
+
+Feel free to try it, and report back problems or ideas as [Github issues](https://github.com/ottopaulsen/node-red-contrib-power-saver/issues).
+
+## Installation
+
+Install in Node-RED via the Manage Palette menu.
+
+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.
+
+## Input
+
+3 different types of input are accepted:
+
+- Tibber
+- Nordpool
+- Other sources in a specific JSON format
+
+Choose the one that fits you best. Of course, all inputs are JSON, but the Tibber and Nordpool alternatives are designed to connect directly to those sources with a minimum effort.
+
+From version 2.1.0, you can also send a config object as input for dynamically changing the node config.
+
+### Tibber input
+
+If you are a Tibber customer, you can use the `tibber-query` node from the [`node-red-contrib-tibber-api` node](https://flows.nodered.org/node/node-red-contrib-tibber-api). Set it up with the following query:
+
+```gql
+{
+  viewer {
+    homes {
+      currentSubscription {
+        priceInfo {
+          today {
+            total
+            startsAt
+          }
+          tomorrow {
+            total
+            startsAt
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Send the result from the `tibber-query` node with the query above directly to the `power-saver` node. Make sure it is refreshed when new prices are ready. Prices for the next day are normally ready at 13:00, but refreshing every hour can be a good idea.
+
+[See example with Tibber, a switch and MQTT](doc/example-tibber-mqtt.md)
+
+### Nordpool input
+
+This is especially designed to work for Home Assistant (HA), and the [Nordpool custom component](https://github.com/custom-components/nordpool). The Nordpool component provides a _sensor_ that gives price per hour for today and tomorrow (after 13:00). Send the output from this sensor directly to the `power-saver` node. Make sure this is done whenever the node is updated, as well as when the system starts up.
+
+Data can be sent from both the `current state` node or the `events: state` node.
+
+[See example with Nordpool and `current state` node](doc/example-nordpool-current-state.md)
+
+[See example with Nordpool and `events: state` node](doc/example-nordpool-events-state.md)
+
+### Other input
+
+If you cannot use any of the two above (Tibber or Nordpool), create the input to the node with the payload containing JSON like this:
+
+```json
+{
+  "today": [
+    { "value": 1, "start": "2021-06-21T00:00:00+02:00" },
+    { "value": 2, "start": "2021-06-21T01:00:00+02:00" }
+    //...
+  ],
+  "tomorrow": [
+    { "value": 3, "start": "2021-06-22T00:00:00+02:00" },
+    { "value": 4, "start": "2021-06-22T01:00:00+02:00" }
+    //...
+  ]
+}
+```
+
+## Output
+
+### Output 1
+
+A payload with the word `true` is sent to output 1 whenever the power / switch shall be turned on.
+
+### Output 2
+
+A payload with the word `false` is sent to output 2 whenever the power / switch shall be turned off.
+
+### Output 3
+
+When a valid input is received, and the schedule is recalculated, 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": "2021-09-30T00:00:00.000+02:00",
+      "value": false
+    },
+    {
+      "time": "2021-09-30T01:00:00.000+02:00",
+      "value": true
+    }
+    //...
+  ],
+  "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
+    }
+    //...
+  ],
+  "source": "Nordpool",
+  "config": {
+    "maxHoursToSaveInSequence": 3,
+    "minHoursOnAfterMaxSequenceSaved": "1",
+    "minSaving": 0.001,
+    "sendCurrentValueWhenRescheduling": true,
+    "outputIfNoSchedule": false
+  }
+}
+```
+
+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, the start time of the hour and the amount per kWh that is saved on hours that are turned off, compared to the next hour that is on.
+
+## Configuration
+
+Currently there is only one strategy for saving. This is the _mostSaved_ strategy. This strategy turns off the hours where the price difference is largest compared to the next hour that is on. The idea is that the power you are not using when the switch is turned off, will be used immediately when the switch is turned on. This would fit well for turning of a water heater or another thermostat controlled heater.
+
+You can configure the following:
+
+- Maximum number of hours to turn off in a sequence.
+- Minimum hours to turn on immediately after a period when turned off the maximum number of hours that is allowed to be turned off.
+- Minimum amount to save per kWh in order to bother turning it off. It is recommended to have some amount here, e.g. 2 cents / 2 øre. No point in saving 0.001, is it?
+- Wether to send on/off just after a reschedule is done without waiting until the next scheduled switch.
+- What to do if there is no valid schedule any more (turn on or off).
+
+### Dynamic config
+
+It is possible to change config dynamically by sending a config message to the node. The config messages has a payload with a config object like this example:
+
+```json
+"payload": {
+  "config": {
+    "maxHoursToSaveInSequence": 4,
+    "minHoursOnAfterMaxSequenceSaved": 2,
+    "minSaving": 0.02,
+    "sendCurrentValueWhenRescheduling": true,
+    "outputIfNoSchedule": true,
+    "scheduleOnlyFromCurrentTime": false
+  }
+}
+```
+
+All the variables in the config object are optional. You can send only those you want to change.
+
+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, the schedule will be replanned based on the last previously received price data. If no price data has been received, no scheduling is done.
+
+## Algorithm
+
+The calculation that decides what hours to turn off works as follows:
+
+1. A matrix (x \* y) is created where x is the number of hours we have price information for, and y is the configured maximum number of hours to turn off in a sequence.
+2. The matrix is filled with how much you save by turning off hour x for y hours.
+3. The matrix is processed calculating all possibilities for turning off a number of hours in a sequence and by that saving money. In this process all non-saving sequences are discarded. Also, if the average saving per hour is less than what you have configured as minimum amount to save per kWh, the sequence is discarded.
+4. The remaining sequences are sorted by how much that is saved, in descending order.
+5. Next, a table with one value per hour is created, with all hours in state "on".
+6. Then the saving sequences is applied one by one, turning off the hours in each sequence, discarding sequences that lead to any violation of the rules set by the config.
+7. When all sequences are processed, the resulting table shows a pretty good savings plan, that in most cases would be the optimal plan.
+
+I say "in most cases", because there is a chance that a group of two or more sequences combined can give a better plan than a single sequence preceeding those two, but where the selection of the one sequence causes the group to be discarded. If anyone encounters this situation, I would be happy to receive the price data set, and try to improve the algorithm even further.
+
+## Integration with MagicMirror
+
+Are you using [MagicMirror](https://magicmirror.builders/)? Are you also using [Tibber](https://tibber.com/)? If so, there is a module for MM called [MMM-Tibber](https://github.com/ottopaulsen/MMM-Tibber), that easily can be used to show savings from this node.
+
+![Show savings in MMM-Tibber](https://github.com/ottopaulsen/MMM-Tibber/blob/master/doc/MMM-Tibber-screenshot-savings-graph.png?raw=true)
+
+The purple lines show savings per kWh.
+
+Read more about this in the [MMM-Tibber documentation](https://github.com/ottopaulsen/MMM-Tibber#show-savings).
+
+## Change Log
+
+See [CHANGELOG.md](CHANGELOG.md)
+
+## Contribute
+
+Contributions are welcome. Please start by creating a Github Issue with suggested changes, and state what you would like to do.

package/docs/nodes/power-saver.md

@@ -0,0 +1,23 @@
+---
+next: ./ps-strategy-best-save.md
+---
+
+# power-saver <Badge type="warning" text="deprecated" vertical="middle" />
+
+![Power Saver node](../images/node-power-saver.png)
+
+This is the node from version 2. It is still working, but should be replaced.
+
+To migrate, just replace the Power Saver node by a combination of the ps-receive-price and the ps-best-save nodes:
+
+Replace the `Power Saver` node from version 2:
+
+![Power Saver node](../images/migrate-power-saver.png)
+
+with this combination of `ps-receive-price` and `ps-strategy-best-save` from version 3:
+
+![Migrate Power Saver](../images/migrate-best-save.png)
+
+The configuration is done in the `ps-strategy-best-save` node, and is the same as in the old `Power Saver` node.
+
+Should you need it, here is the [old documentation](./old-power-saver-doc) for the PowerSaver node from version 2.

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

@@ -0,0 +1,52 @@
+# ps-elvia-add-tariff
+
+![ps-elvia-add-tariff](../images/node-ps-elvia-add-tariff.png)
+
+Node to add grid tariff from Elvia.
+
+::: warning Elvia API
+You need an Elvia API subscription key to use this node. See [configuration](#elvia-configuration).
+:::
+
+## Description
+
+When grid tariff changes from hour to hour, this should normally also be considered when finding the most favorable hours to use power. This node retrieves prices from Elvia, so if you are an elvia customer, you can put this node between the `ps-receive-price` node and the strategy nodes. When configured, it will add Elvia tariff to the power prices before doing the calculation:
+
+![Elvia flow](../images/elvia-flow.png)
+
+## Configuration
+
+::: warning Elvia API subscription key
+This node uses the Elvia API, and you must get your own Elvia API subscription key in order to use it.
+Go to the [Elvia Developer Portal](https://elvia.portal.azure-api.net/) to sign up,
+and then request for a subscription to the GridTariffAPI.
+When your subscription is approved, you will find your subscription key in the
+[developer portal](https://elvia.portal.azure-api.net/developer) under Your subscriptions.
+:::
+
+The first time you use this node, you must create a `ps-elvia-config` entry. Click on the edit button to the right of Elvia Config:
+
+![Elvia configuration](../images/elvia-config-no-config.png)
+
+Then enter the Elvia API subscription key:
+
+![Elvia configuration](../images/elvia-config-subscription-key.png)
+
+After entering the Elvia API subscription key the first time, it is not possible to select tariff.
+
+![Elvia configuration](../images/elvia-config-no-tariff.png)
+
+To fix that, save the config, deploy, and then open the node again.
+Now you should be able to select the right tariff:
+
+![Elvia configuration](../images/elvia-config-select-tariff.png)
+
+The next time you use this node, you can select the same config as you created the first time, and then you can also select tariff immediately.
+
+## Input
+
+The input is the [common strategy input format](./strategy-input.md)
+
+## Output
+
+The input is the [common strategy input format](./strategy-input.md)