Important notice about the fundamental difference between versions 3.x and 4.x

Versions 3.x and 4.x of openHAB Spot Price Optimizer have a fundamental difference which must be understood before updating from 3.x to 4.x

• Version 3.x has a capability to fetch weather forecast from the (FMI) Finnish Meteorology Institute's API and to fetch spot prices from Entso-E API. The reason for this is that when the solution was originally developed in 2022, openHAB did not support persisting timeseries data with future timestamps. To overcome this limitation, version 3.x completely bypasses the openHAB persistence layer and interacts directly with the InfluxDB.
• openHAB version 4.2 introduced support to persist timeseries with future timestamps which allows openHAB Bindings to store forecasts as a proper timeseries. Thanks to this great improvement, version 4.x of openHAB Spot Price Optimizer can now focus solely on optimization algorithms and leave the fetching of spot prices and weather forecasts to Bindings which are dedicated just for that purpose. You can use your favorite Binding as long as they persist the weather forecast and spot price data as a proper forecast timeseries.
  • FMI Weather Binding is known to work with this solution and provides data for Scandinavia but as mentioned, any weather forecast binding which persists the data as a proper forecast timeseries will work.
  • Entso-E Binding included in the upcoming openHAB 4.3.0 is known to work with this solution but as mentioned, any binding which persists the price data as a proper forecast timeseries will work.
• openHAB Spot Price Optimizer 3.x is considered deprecated and will be supported with bugfixes until 10 June 2025. All new features will only go to version 4.x of openHAB Spot Price Optimizer.

Installation instructions for completely new installs

The following instructions will install version 4.x of openHAB Spot Price Optimizer. You can install version 3.x if you prefer to do so but be aware that it is considered deprecated.

• Ensure that all pre-requisites have been met.
• The openhab-spot-price-optimizer is written in Javascript and published as a npm package.
• Go to the command line of your openHAB server and navigate to your openHAB automation/js directory.
  • If you are using openHABian opearting system image, this is /etc/openhab/automation/js
• Install the package with a command npm install openhab-spot-price-optimizer@4
  • WARNING: If you have previously added scripts to the automation/js/node_modules directory manually, make a backup of them before npm install as it will will erase all files and directories under node_modules which are not installed with the npm install command.
  • This will create a directory automation/js/node_modules (if it does not exist already) and automatically download the latest version of openhab-spot-price-optimizer there
• You can now write openHAB Rules or Scripts to calculate the needed amount of heating based on the weather forecast and use the optimization algorithms. See examples from separate wiki pages.

Update instructions for minor updates

These instructions apply for minor updates, for example from 4.0.2 to 4.1.0. If you are doing a major update for example from 3.x to 4.x, see separate instructions below.

• Go to the command line of your openHAB server and navigate to automation/js directory under openHAB conf.
  • If you are using openHABian operating system image, this is /etc/openhab/automation/js
• Update the module to the latest version with command npm update openhab-spot-price-optimizer
• Go to Settings / Rules on your openHAB installation. Re-save all Rules that use openhab-spot-price-optimizer to refresh openHAB javascript cache.
• Test your rules and check your openHAB logs.

Instructions when upgrading 2.x/3.x to version 4.x

As mentioned above, version 4.x has fundamental changes compared to the previous versions. Many existing users will also update to openHAB 4.3.0 at the same go. The instructions below contains the recommended order for performing the updates.

Pause all your controller Rules

• You have one or more controller rules which are running every 15 minutes / every hour and which toggle your devices ON or OFF
• Pause all these rules so that they are not getting triggered in the middle of your update process.

Pause the FetchSpotPrices Rule

• openHAB Spot Price Optimizer 2.x and 3.x had a rule FetchSpotPrices which called the Entso-E API to fetch spot prices.
• This task is now delegated to the Entso-E Binding (or some other price binding). Pause this old rule for the time being.
• Once you have completed your upgrade process, remove the Rule permanently so that you won't accidentally activate it.

Pause the FetchWeatherForecast Rule

• openHAB Spot Price Optimizer 2.x and 3.x had a rule FetchWeatherForecast which called the FMI API to fetch weather forecast.
• This task is now delegated to the weather Bindings. Pause this old rule for the time being.
• Once you have completed your upgrade process, remove the Rule permanently so that you won't accidentally activate it.

Pause your optimization rules

• Your existing solution has script actions that do the actual optimizations.
• These are either separate Rules or additional Actions in the FetchSpotPrices rule. If these are separate rules, pause them for the time being.

Update your openHAB to version 4.3.0 or higher

• Once you have paused the rules listed above, update your openHAB to version 4.3.0 or higher.
• The EntsoE and FMI Weather bindings with timeseries support are included from openHAB version 4.3.0 onwards.

Install and configure Entso-E binding, re-create the SpotPrice item.

• Install the Entso-E binding from Settings / Add-on store.
• Copy the Entso-E security token from your old config.js file to the Entso-E binding settings.
• You previously had an Item called SpotPrice. The name of the item can obviously be different if you previously used some other name. Delete this old item and re-create it with the same name from the Spot Price Channel of the Entso-E Binding. (Deleting the old Item does not delete previously stored data from your database, it only removes it from openHAB, so this is a safe operation to do).
• The reason why it is recommended to delete and re-create the Item with the same name has everything to do with the unit of measure of the item. The Entso-E binding provides the data as EUR/kWh whereas most users on the Euro zone prefer to use c/kWh. The way to achieve this is documented on the separate wiki page of the Entso-E binding.
• Important: The SpotPrice item must use the forecast persistence strategy, and only that. It is highly recommended to use an AllForecastItems Item Group and configure the persistence strategies using this group. Details for creating this group can be found on the EntsoE Binding wiki page linked above.
• Verify that the binding works as expected before proceeding to the next step.
• Entso-E binding has a configuration option to specify how many days of history you want to load. Make sure to use at least 1 day here. See considerations for existing data below.

Install and configure FMI Weather binding, re-create the weather forecast items.

• Install the FMI Weather binding or any other binding that can persist the weather forecast as a real timeseries.
• You previously had an Item called FMIForecastTemperature. The name of the item can obviously be different if you previously used some other name.
• Go to the FMI Weather Thing's channels and link the Temperature forecast channel to this existing Item.
• See a separate documentation page on how to install and configure FMI Weather Binding
• Important: The temperature forecast item must use the forecast persistence strategy, and only that. It is highly recommended to use an AllForecastItems Item Group and configure the persistence strategies using this group. If you are following this recommendation and configured the persistence policies in the previous step for the AllForecastItems group, all you need to do now is to add the temperature forecast item to this group.
• Verify that the binding works as expected before proceeding to the next step.

Update openHAB Spot Price Optimizer to version 4.x.x

• You should now have openHAB updated to version 4.3.0 or higher and Entso-E and FMI Weather Bindings have been configured.
• Update openHAB Spot Price Optimizer npm package to version 4:
  • Go to the command line of your openHAB server and navigate to your openHAB automation/js directory.
  • If you are using openHABian operating system image, this is /etc/openhab/automation/js
  • Update the module to version 4 with command npm install openhab-spot-price-optimizer@4

Add all your control point items and optional other price items to the AllForecastItems persistence strategy

• By now you should already have a persistence strategy configured for the AllForecastItems group.
• Add all your control point items (such as BoilerControl, HeatPumpCompressorControl) to this group.
• If you're using the TariffCalculator to calculate distribution price and total price, also add those Items to this same group.

Considerations for existing spot price data

• Previous version of openHAB Spot Price Optimizer used a 15 minute resolution for storing the prices.
• Entso-E binding provides the data in 60 minute resolution and from midnight to midnight on Central European Timezone.
• For example Finland is one hour ahead of CET, which means that Entso-E provides the prices from 01:00 to 01:00 every day.
• If (when) you run your optimizations from midnight to midnight, you must ensure that you have data with the same resolution for every single hour of your optimization window.
• In other words, you must overwrite the previous 15 minute resolution data with fresh data delivered by the Entso-E binding.
• In the Entso-E binding settings, define the Historic Data parameter to contain a value of 3 days. This will overwrite the previous 15 minute resolution prices with 60 minute prices, including the first hour from 00:00 to 01:00, which means that everything will work as expected when you run the optimizations.

Considerations for existing distribution price and total price data

• If you have previously used the optional TariffCalculator to calculate the distribution price and total price, your DistributionPrice and TotalPrice items have existing data with 15 minute resolution which must be overwritten with 60 minute resolution.
• Create a new Rule for calculating the distribution price and total price. Instructions are provided on the separate wiki page.
• Once you have your new Rule for calculating the distribution price and total price, run it initially for 3 days in the history and 1 day to the future. If you are in another timezone than CET, remember to adjust the start time. For example users in Finland could use

var start = time.toZDT('01:00').minusDays(3);
var end   = time.toZDT('01:00').plusDays(2);

Modify all your optimization Rules

• All your optimization rules need small modifications since we are now interacting with openHAB persistence layer instead of using the influx.js service which was bypassing the openHAB persistence layer in versions 2.x and 3.x
• First take a backup of your old script actions to a text file so that you can compare what you had before.
• Carefully examine the documentation examples for version 4.x and compare those to your current Rule scripts
  • Usage example for GenericOptimizer
  • Usage example for HeatingPeriodOptimizer

Key changes in the scripts

1. Remove references to Influx service.

2. Prices are now read directly from openHAB persistence service like this:

// Define the optimization window
var start = time.toZDT('00:00').plusDays(1);
var end = start.plusDays(1);

// Define price item and read prices from openHAB persistence service
var priceItem = items.getItem('SpotPrice');
var prices = priceItem.persistence.getAllStatesBetween(start, end);

3. At the end of the Rule, the GenericOptimizer returns a timeseries of control points, which can be saved to the database like this:

// Get control points from the GenericOptimizer service
var timeseries = optimizer.getControlPoints();

// Define your control item and save the control points to the database
var controlItem = items.getItem('BoilerControl'); 
controlItem.persistence.persist(timeseries);

4. Also notice that the Rules need a delay. Examples are provided on the documentation pages linked above. The background for this is that the optimization Rules are triggered as soon as the Entso-E binding fires the prices-received trigger channel. At this time, the openHAB process that writes the prices to your database is most probably not yet completed, so the optimization Rules do not yet have the price data available.

Modify your controller Rules

• The controller Rules are the ones which are executed every 15 minutes and which change the state of the Items that control your devices.
• Previously these Rules read the control points from the database using the influx.js. Now we want to read the control points using the openHAB persistence layer.
• First take a backup of your old script actions to a text file so that you can compare what you had before.
• Modify the controller rule according to the example documented on the separate wiki page.

Modify your chart configuration

If you have created a Chart page that visualizes the price data together with your control points, the chart needs small adjustments.

Change step-line from middle to end

• The resolution of the price data will be 60 minutes in most countries whereas the resolution of your control points remain as 15 minutes
• Previously the step-line for prices was configured so that the point is in the middle of the line as illustrated in the screenshot above
• Now the step-line for prices need to be end of the line so that the prices and control points will be displayed correctly.
• The change needs to be done in the YAML code of your chart page, the screenshot below highlights the line which needs to be changed.

Apply the new settings introduced in openHAB 4.3.0

• In the chart configuration, click "Configure series" for each time series that you have in your chart
• Enable advance settings, and ensure that Don't include boundary and Don't include Item state are enabled
• If you have multiple persistence services running (such as InfluxDB and RRD4j), ensure that your chart is rendering the data from the InfluxDB persistence service.
• Screenshot below highlights these configuration options.

(Note that openHAB will render the price data so that the last price point is at 23:00. Previously the price points for 23:15, 23:30 and 23:45 were present as well so they were displayed but now that the price resolution is 60 minutes, the price point of 23:00 is the last one of the day and thus that is the last point that will be displayed.)