OH 4.1 introduced a new subsystem (for lack of a better word) that supports monetary units. These can be used for things like calculating/estimating the month’s power bill and the like.
Configure the Provider
Currently the support is pretty basic and supports just one currency. But in the future there is a plan to support additional providers with connections to exchanges where values can be converted between currencies using the current exchange rates.
But this means that you have to configure a provider to start. Otherwise your Items will just appear to have unit DEF
.
There are two providers supported right now. The “FixedCurrencyProvider” will let you just define what currency you want to use everywhere. The “LocaleBasedCurrencyProvider” will use your regional settings to determine the default currency. The units follow ISO 4217 three letter designations (e.g. USD, EUR, etc.).
- Navigate to Settings and under “System Settings” click on “Unit Settings”.
- Choose the desired provider and if choosing “FixedCurrencyProvider” supply the default unit.
Configure the Item(s)
There are two new types of Items: Number:Currency
and Number:EnergyPrice
.
Number:Currency
This Item represents an amount of money. Define the Item as a Number:Currency
. As with other units the default representation will be a floating point number followed by the unit, for example 123.456789 $
. Therefore you’ll want to configure the State Description pattern to only show two decimal places and show the unit in front of the number (if that’s how it’s usually done for your currency of support).
value: " "
config:
pattern: $%.2f
Number:EnergyPrice
This type of Item represents the amount of cost per kWh of energy (other per unit cost situations like per gallon/liter are not yet supported). The unit for this Item is going to be DEF/kWh
where DEF
gets replaced by the provider with your configure currency.
Calculating with Currency
Here I’ll show a simple example of calculating using these Item that takes the monthly energy reading and calculates the monthly bill based on the access rate and per kWh rate.
The Items
Number:Energy HomeEnergyMeter_ElectricmeterkWh
Number:Currency HomeEnergyMeter_Access
Number:EnergyPrice HomeEnergyMeter_Rate
Number:Currency HomeEnergyMeter_CurrentBillEstimate
The first comes from a power meter (a Zwave whole house energy sensor in my case). The second two come from my power bill and are set manually. The last one is the result of the calculation.
The Rule
In JS Scripting:
configuration: {}
triggers:
- id: "1"
configuration:
itemName: HomeEnergyMeter_ElectricmeterkWh
type: core.ItemStateChangeTrigger
- id: "2"
configuration:
itemName: HomeEnergyMeter_Access
type: core.ItemStateChangeTrigger
- id: "3"
configuration:
itemName: HomeEnergyMeter_Rate
type: core.ItemStateChangeTrigger
conditions: []
actions:
- inputs: {}
id: "4"
label: Calculate the power bill and update the Item
configuration:
type: application/javascript;version=ECMAScript-2021
script: >-
var curr = items.HomeEnergyMeter_ElectricmeterkWh.quantityState;
var rate = items.HomeEnergyMeter_Rate.quantityState;
var access = items.HomeEnergyMeter_Access.quantityState;
var usage = curr.multiply(rate);
var estimate = access.add((curr.multiply(rate)));
items.HomeEnergyMeter_CurrentBillEstimate.postUpdate(estimate);
type: script.ScriptAction
Trigger the rule when any of the Items the calculation depends on changes. First get the three values for the calculation as Quantity types (i.e. don’t throw away the units).
Multiply the current kWh reading by the energy price rate. The kWh
units cancel out resulting in just a monetary value. Then add the line access fee to get the total power bill for the month thus far.
In Blockly it would look like the following.