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.

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

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

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)