# 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.

# 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 (opens new window).

# 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:

Bridge awattar:bridge:bridge1 "aWATTar Bridge" [ country="DE", vatPercent="19", basePrice="17.22"] {
 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:

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

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.

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)

← AVM FRITZ! Belkin Wemo →