# aWATTar Binding

This binding provides access to the hourly prices for electricity for the German and Austrian provider aWATTar.

## Supported Things

There are three supported things.

### aWATTar Bridge

The `bridge` reads price data from the aWATTar API and stores the (optional) config values for VAT and energy base price.

### Prices Thing

The `prices` Thing provides todays and (after 14:00) tomorrows net and gross prices.

### Bestprice Thing

The `bestprice` Thing identifies the hours with the cheapest prices based on the given parameters.

Note: The Thing will schedule updates of the aWATTar API at 15:00, 18:00 and 21:00.
If late updates occur, e.g. after 21:00, there is a chance that consecutive best prices will be rescheduled.
As a consequence, a time schedule spanning over an update slot might be interrupted and rescheduled.

## Discovery

Auto discovery is not supported.

## Thing Configuration

### aWATTar Bridge

| Parameter  | Description                                                                                                                                                                                                                                                                                                     |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| vatPercent | Percentage of the value added tax to apply to net prices. Optional, defaults to 19.                                                                                                                                                                                                                             |
| basePrice  | The net(!) base price you have to pay for every kWh. Optional, but you most probably want to set it based on you delivery contract.                                                                                                                                                                             |
| timeZone   | The time zone the hour definitions of the things below refer to. Default is `CET`, as it corresponds to the aWATTar API. It is strongly recommended not to change this. However, if you do so, be aware that the prices delivered by the API will not cover a whole calendar day in this timezone. **Advanced** |
| country    | The country prices should be received for. Use `DE` for Germany or `AT` for Austria. `DE` is the default.                                                                                                                                                                                                       |
| serviceFee | The service fee in percent. Will be added to the total price. Will be calculated on top of the absolute price per hour. Default is `0`.                                                                                                                                                                         |

### Prices Thing

The prices thing does not need any configuration.

### Bestprice Thing

| Parameter     | Description                                                                                                                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| rangeStart    | First hour of the time range the binding should search for the best prices. Default: `0`                                                                                                                     |
| rangeDuration | The duration of the time range the binding should search for best prices. Default: `24`                                                                                                                      |
| length        | number of best price hours to find within the range. This value has to be at least `1` and below `rangeDuration` Default: `1`                                                                                |
| consecutive   | if `true`, the thing identifies the cheapest consecutive range of `length` hours within the lookup range. Otherwise, the thing contains the cheapest `length` hours within the lookup range. Default: `true` |
| inverted      | if `true`, the worst prices will be searched instead of the best. Does currently not work in combination with 'consecutive'. Default: `false`                                                                |

#### Limitations

The channels of a bestprice thing are only defined when the binding has enough data to compute them.
The thing is recomputed after the end of the candidate time range for the next day, but only as soon as data for the next day is available from the aWATTar API, which is around 14:00.
So for a bestprice thing with `[ rangeStart=5, rangeDuration=5  ]` all channels will be undefined from 10:00 to 14:00.
Also, due to the time the aWATTar API delivers the data for the next day, it doesn't make sense to define a thing with `[ rangeStart=12, rangeDuration=20 ]` as the binding will be able to compute the channels only after 14:00.

## Channels

### Bridge

The bridge has two channels which support a time-series:

| channel      | type               | description                                                                                                                             |
| ------------ |--------------------| --------------------------------------------------------------------------------------------------------------------------------------- |
| market-net   | Number:EnergyPrice | This net market price per kWh. This is directly taken from the price the aWATTar API delivers.                                          |
| total-net    | Number:EnergyPrice | Sum of net market price and configured base price                                                                                       |

If you need gross prices, please use the [VAT profile](https://www.openhab.org/addons/transformations/vat/).

### Prices Thing

For every hour, the `prices` thing provides the following prices:

| channel      | type   | description                                                                                                                             |
| ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| market-net   | Number | This net market price per kWh. This is directly taken from the price the aWATTar API delivers.                                          |
| market-gross | Number | The market price including VAT, using the defined VAT percentage.                                                                       |
| total-net    | Number | Sum of net market price and configured base price                                                                                       |
| total-gross  | Number | Sum of market and base price with VAT applied. Most probably this is the final price you will have to pay for one kWh in a certain hour |

All prices are available in each of the following channel groups:

| channel group                          | description                                                                                                                                                                          |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| current                                | The prices for the current hour                                                                                                                                                      |
| today00, today01, today02 ... today23  | Hourly prices for today. `today00` provides the price from 0:00 to 1:00, `today01` from 1:00 to 02:00 and so on. As long as the API is working, this data should always be available |
| tomorrow00, tomorrow01, ... tomorrow23 | Hourly prices for the next day. They should be available starting at  14:00.                                                                                                         |

### Bestprice Thing

| channel   | type        | description                                                                                                                                                                                               |
| --------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| active    | Switch      | `ON` if the current time is within the bestprice period, `OFF` otherwise. If `consecutive` was set to `false`, this channel may change between `ON` and `OFF` multiple times within the bestprice period. |
| start     | DateTime    | The exact start time of the bestprice range. If `consecutive` was `false`, it is the start time of the first hour found.                                                                                  |
| end       | DateTime    | The exact end time of the bestprice range. If `consecutive` was `false`, it is the end time of the last hour found.                                                                                       |
| countdown | Number:Time | The time in minutes until start of the bestprice range. If start time passed. the channel will be set to `UNDEFINED` until the values for the next day are available.                                     |
| remaining | Number:Time | The time in minutes until end of the bestprice range. If start time passed. the channel will be set to `UNDEFINED` until the values for the next day are available.                                       |
| hours     | String      | A comma separated list of hours this bestprice period contains.                                                                                                                                           |

## Full Example

### Things

awattar.things:

```java
Bridge awattar:bridge:bridge1 "aWATTar Bridge" [ country="DE", vatPercent="19", basePrice="17.22", serviceFee="3" ] {
 Thing prices price1 "aWATTar Price" []
// The car should be loaded for 4 hours during the night
 Thing bestprice carloader "Car Loader" [ rangeStart="22", rangeDuration="8", length="4", consecutive="true" ]
// In the cheapest hour of the night the garden should be watered
 Thing bestprice water "Water timer" [ rangeStart="19", rangeDuration="12", length="1" ]
// The heatpump should run the 12 cheapest hours per day
 Thing bestprice heatpump "Heat pump" [ length="12", consecutive="false" ]
}
```

### Items

awattar.items:

```java
Number:Dimensionless currentnet "Current price [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:current#market-net" }
Number:Dimensionless currentgross "Current price [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:current#market-gross" }
Number:Dimensionless totalnet "Current price [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:current#total-net" }
Number:Dimensionless totalgross "Current price [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:current#total-gross" }
Number:Dimensionless totalgross "Current price [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:current#total-gross" }

Number:Dimensionless today00 "Today 00-01 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today00#total-gross" }
Number:Dimensionless today01 "Today 01-02 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today01#total-gross" }
Number:Dimensionless today02 "Today 02-03 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today02#total-gross" }
Number:Dimensionless today03 "Today 03-04 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today03#total-gross" }
Number:Dimensionless today04 "Today 04-05 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today04#total-gross" }
Number:Dimensionless today05 "Today 05-06 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today05#total-gross" }
Number:Dimensionless today06 "Today 06-07 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today06#total-gross" }
Number:Dimensionless today07 "Today 07-08 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today07#total-gross" }
Number:Dimensionless today08 "Today 08-09 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today08#total-gross" }
Number:Dimensionless today09 "Today 09-10 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today09#total-gross" }
Number:Dimensionless today10 "Today 10-11 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today10#total-gross" }
Number:Dimensionless today11 "Today 11-12 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today11#total-gross" }
Number:Dimensionless today12 "Today 12-13 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today12#total-gross" }
Number:Dimensionless today13 "Today 13-14 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today13#total-gross" }
Number:Dimensionless today14 "Today 14-15 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today14#total-gross" }
Number:Dimensionless today15 "Today 15-16 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today15#total-gross" }
Number:Dimensionless today16 "Today 16-17 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today16#total-gross" }
Number:Dimensionless today17 "Today 17-18 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today17#total-gross" }
Number:Dimensionless today18 "Today 18-19 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today18#total-gross" }
Number:Dimensionless today19 "Today 19-20 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today19#total-gross" }
Number:Dimensionless today20 "Today 20-21 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today20#total-gross" }
Number:Dimensionless today21 "Today 21-22 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today21#total-gross" }
Number:Dimensionless today22 "Today 22-23 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today22#total-gross" }
Number:Dimensionless today23 "Today 23-00 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:today23#total-gross" }

Number:Dimensionless tomorrow00 "Tomorrow 00-01 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow00#total-gross" }
Number:Dimensionless tomorrow01 "Tomorrow 01-02 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow01#total-gross" }
Number:Dimensionless tomorrow02 "Tomorrow 02-03 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow02#total-gross" }
Number:Dimensionless tomorrow03 "Tomorrow 03-04 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow03#total-gross" }
Number:Dimensionless tomorrow04 "Tomorrow 04-05 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow04#total-gross" }
Number:Dimensionless tomorrow05 "Tomorrow 05-06 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow05#total-gross" }
Number:Dimensionless tomorrow06 "Tomorrow 06-07 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow06#total-gross" }
Number:Dimensionless tomorrow07 "Tomorrow 07-08 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow07#total-gross" }
Number:Dimensionless tomorrow08 "Tomorrow 08-09 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow08#total-gross" }
Number:Dimensionless tomorrow09 "Tomorrow 09-10 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow09#total-gross" }
Number:Dimensionless tomorrow10 "Tomorrow 10-11 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow10#total-gross" }
Number:Dimensionless tomorrow11 "Tomorrow 11-12 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow11#total-gross" }
Number:Dimensionless tomorrow12 "Tomorrow 12-13 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow12#total-gross" }
Number:Dimensionless tomorrow13 "Tomorrow 13-14 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow13#total-gross" }
Number:Dimensionless tomorrow14 "Tomorrow 14-15 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow14#total-gross" }
Number:Dimensionless tomorrow15 "Tomorrow 15-16 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow15#total-gross" }
Number:Dimensionless tomorrow16 "Tomorrow 16-17 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow16#total-gross" }
Number:Dimensionless tomorrow17 "Tomorrow 17-18 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow17#total-gross" }
Number:Dimensionless tomorrow18 "Tomorrow 18-19 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow18#total-gross" }
Number:Dimensionless tomorrow19 "Tomorrow 19-20 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow19#total-gross" }
Number:Dimensionless tomorrow20 "Tomorrow 20-21 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow20#total-gross" }
Number:Dimensionless tomorrow21 "Tomorrow 21-22 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow21#total-gross" }
Number:Dimensionless tomorrow22 "Tomorrow 22-23 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow22#total-gross" }
Number:Dimensionless tomorrow23 "Tomorrow 23-00 [%2.2f ct/kWh]"  { channel="awattar:prices:bridge1:price1:tomorrow23#total-gross" }

DateTime CarStart "Start car loader [%1$tH:%1$tM]"  { channel="awattar:bestprice:bridge1:carloader:start" }
DateTime CarEnd "End car loader [%1$tH:%1$tM]"  { channel="awattar:bestprice:bridge1:carloader:end" }
String CarCountdown "Countdown for car loader [%s]"  { channel="awattar:bestprice:bridge1:carloader:countdown" }
String CarHours "Hours for car loader [%s]"  { channel="awattar:bestprice:bridge1:carloader:hours" }
Switch CarActive { channel="awattar:bestprice:bridge1:carloader:active" }

Switch WaterActive { channel="awattar:bestprice:bridge1:water:active" }
Switch HeatpumpActive { channel="awattar:bestprice:bridge1:heatpump:active" }
```

### Sitemap

```perl
sitemap default label="aWATTar Sitemap"
{
 Frame label="Car Loader" {
  Switch item=CarActive
  Text item=CarCountdown
  Text item=CarStart
  Text item=CarEnd
  Text item=CarHours
 }
 Frame label="Current Prices" {
  Text label="Current Net" item=currentnet
  Text label="Current Gross" item=currentgross
  Text label="Total Net" item=totalnet
  Text label="Total Gross" item=totalgross
 }
 Frame label="Todays Prices (total gross)" {
  Text item=today00
  Text item=today01
  Text item=today02
  Text item=today03
  Text item=today04
  Text item=today05
  Text item=today06
  Text item=today07
  Text item=today08
  Text item=today09
  Text item=today10
  Text item=today11
  Text item=today12
  Text item=today13
  Text item=today14
  Text item=today15
  Text item=today16
  Text item=today17
  Text item=today18
  Text item=today19
  Text item=today20
  Text item=today21
  Text item=today22
  Text item=today23
 }
 Frame label="Tomorrows Prices (total gross)" {
  Text item=tomorrow00
  Text item=tomorrow01
  Text item=tomorrow02
  Text item=tomorrow03
  Text item=tomorrow04
  Text item=tomorrow05
  Text item=tomorrow06
  Text item=tomorrow07
  Text item=tomorrow08
  Text item=tomorrow09
  Text item=tomorrow10
  Text item=tomorrow11
  Text item=tomorrow12
  Text item=tomorrow13
  Text item=tomorrow14
  Text item=tomorrow15
  Text item=tomorrow16
  Text item=tomorrow17
  Text item=tomorrow18
  Text item=tomorrow19
  Text item=tomorrow20
  Text item=tomorrow21
  Text item=tomorrow22
  Text item=tomorrow23
 }
}
```

### Usage hints

The idea of this binding is to support both automated and non automated components of your home.
For automated components, just decide when and how long you want to power them on and use the `active` switch of the bestprice thing to do so.
Many non automated components still allow some kind of locally programmed start and end times, e.g. washing machines or dishwashers.
So if you know your dishwasher needs less than 3 hour for one run and you want it to be done the next morning, use either the `countdown` or the `remaining` channel of a bestprice thing to determine the best start or end time to select.
