openHAB Persistence Tutorial: Restore Items on Startup

Have you noticed that when you restart your openHAB server, the value of your items gets lost? The reason is that, by default, openHAB doesn't store any value. This means that every time you restart the server, you lose the status of every single one of them.

Quite frankly, this stinks, especially when you have gadgets that don't give updates on a regular basis, like my MiLight Smart Lights.

For now, let's just focus on explaining what openHAB Persistence is and how it might be beneficial for your home automation project.

This post is part of a series of three pieces on openHAB Persistence:

1. openHAB Persistence Part 1: Restore The Value if your Items on Startup.
2. openHAB Persistence Part 2: Build Graphs Using InfluxDB and Grafana.
3. openHAB Persistence Part 3: Using Persistence in your rules.

What Is openHAB Persistence?

Persistence provides openHAB with the ability to store the value of some or all of your items on a timely basis so you can leverage those values later for different purposes.

How Can You Benefit From Implementing openHAB  Persistence?

There are three main use cases where implementing openHAB Persistence can be a game changer:

• Reload on Restart: The simplest, and arguably the most useful, one is to restore the value of your items after a restart. I think this is a must for any implementation.
• Creating Charts for Data Analysis: A home automation system can help you with saving money, time, and energy, but you need to be able to analyze the data first. Charts are a great way of accomplishing that.
• Access to previous values in your rules: The ability to access past data can be a very powerful feature. For example, if you know that the temperature in a room is trending up, you can choose not to trigger the heat and let nature do its thing, hence saving energy.

This is the first of a three-post series about openHAB Persistence. I will be covering every single one of the use cases that I mentioned above. Let's get started!

How to Restore openHAB Items on Startup?

openHAB Persistence can be a very powerful tool. It can give you an insane amount of insight about what is going on at home. On the flip side, it can also be very resource-hungry.

But, what if you only need to restore the value of your items? There are many ways of implementing openHAB Persistence, but if this is the only thing you need to accomplish, the majority of them is a massive overkill.

There is a middle ground in this case, and it is called MapDB. 

Restore the Value of Your Items on Startup Using MapDB

What makes MapDB so unique is that it only keeps one value at a time per item. It is not meant to be used for chart generation or to access previous values. It is very lightweight and the perfect solution for this use case.

Let's get started!

Install the MapDB openHAB Persistence Service

The first thing that you need to do is to install the MapDB persistence service. In order to do that, go to Addons on the PaperUI and navigate to the option Persistence.

Select MapDB Persistence and click on Install, as you would do with any other binding.

After the service is installed, you need to select MapDB as your preferred openHAB Persistence service. You need to do this if you have only one service.

This step is very simple, just to go to Configuration -> System and scroll down until you see a section called Persistence. Here, you can specify MapDB as your preferred option.

We are done with the installation, and now it is time to configure the items that you want to persist the value.

Configure MapDB

PaperUI doesn't support this part of the configuration so you will have to do some tinkering with the config files — don't worry, it is not super complex.

If you are running openHABian, you should already have a shared folder where you can access the configuration from your desktop computer. If you don't have a shared folder, you can always log into your openHAB server using SSH.

Shared folder from your desktop:  \\OPENHABIANPI\openHAB-conf\persistence 

Path directly on the server:  /etc/openhab2/persistence 

On the Persistence folder, you should see a file called  mapdb.persist. If it isn't there, don't panic — just create an empty file with that name.

You have the file, now what? If you are looking for the quick and easy answer, here it is.

Just paste the following content on the  mapdb.persist file, restart the Raspberry Pi, and you are good to go.

Strategies {
}

Items {
   *: strategy = everyChange, restoreOnStartup
}

Are you still here? The configuration above covers the use case that I presented initially, using it you will get the value of your items restored every time you restart the server

If you are curious about why that configuration works and want to learn more about it, stick around.

openHAB Persistence Tutorial

This section is not very relevant for MapDB, although it will be crucial for the next two parts of the series.

The configuration file for MapDB can be broken down into two sections, strategies, and items.

Strategies

A strategy defines when the value of a given item should be stored. You can define several strategies and apply them to the different items that you want to store.

Strategies {
   everyHour : "0 0 * * * ?"
   everyDayAtMidnight : "0 0 0 * * ?"
   default = everyChange
}

In the example above, I have configured two strategies (don't worry about the default one yet). The first one will store the value of an item every hour; the second one will do it every day at midnight.

If you are wondering how the expression "0 0 0 * * ?" magically translates into "Execute something every day at midnight," you will need to do some learning about Cron expressions. I know — it doesn't seem very intuitive at first. If you want to know how to create your own Cron expressions, check out this website Cron Expression Generator. It is pretty neat!

The custom strategies are handy for very specific use cases, but openHAB provides predefined ones that cover most scenarios.

Predefined Strategies

•  everyChange: It persists the value of the item only when it changes.
•  everyUpdate: It persists the value of an item when it receives an update, even if the value hasn't changed.
•  restoreOnStartup: This strategy is the whole objective of the tutorial. When you add it to an item or group of items, the value gets restored on startup.

 everyChange and  everyUpdate sound exactly the same for you? You are not the only one!

Here is an example to help you understand. If the difference seems obvious to you, just skip this part.

Scenario 1: The temperature on your thermostat changes from 70 to 72 degrees.

Expected Behavior: Both strategies everyChange and everyUpdate will write the value of your item.

Scenario 2: The temperature on your thermostat receives an update with the value 70, but the temperature was already 70 before — it hasn't changed.

Expected Behavior: Only if the strategy is everyUpdate, the value will be stored as a new record.

I don't really find many cases where the strategy everyUpdate can be useful, do you? Let me know in the comments below.

The default strategy in the definition above is pretty self-explanatory. If an item doesn't have a strategy assigned, it will apply everyChange.

Items

This section defines the items that you want to persist the value for.

Items {
    <itemlist1> : [strategy = <strategy1>, <strategy2>, ...]
    <itemlist2> : [strategy = <strategyX>, <strategyY>, ...]
    ...

}

Let's go through a few examples:

Items {
  * : strategy = everyChange, restoreOnStartup
}

The start symbol ( * ) applies to all the items in your openHAB configuration.

Items {
  milight_entrance_color,milight_livingroom_color : strategy = everyChange, restoreOnStartup
  milight_kitchen_color : strategy = everyUpdate, restoreOnStartup
  mqtt_livingroom_temperature
}

The configuration above stores the value for four items only.

•  milight_entrance_color and milight_livingroom_color  will use the everyChange strategy and restore the values on startup.
•  milight_kitchen_color will use everyUpdateand restore the value on startup.
•  mqtt_livingroom_temperature will use the default strategy.

Items {
  gSensors : strategy = everyChange, restoreOnStartup
  gSensors*: strategy = everyChange, restoreOnStartup
}

In order to store the value of all the members of a group, you will specify it like this: <GroupName>*.

You may have noticed that I have added the value gSensors separately. The reason is that gSensors* persists the value of the group members but not the group itself.

Let's wrap out with a full example. For the sake of clarity, I will add the comments directly in the config file.

Strategies 
  { 
  //The value of the item is persisted every hour. 
  everyHour : "0 0 * * * ?"
  //Every day at midnight, an even is fired to store the value 
  everyDayAtMidnight : "0 0 0 * * ?"
  //Every Tuesday at 5PM...I can't really find a legitimate use for this...
  everyTuesdayAtFive : "0 0 0,17 ? * TUE *" 
  //If no strategy is defined, everyChange will be used.
  default = everyChange 
  }

Items 
  {
  //Persist the value for all the members of the group gTemperatureSensors using the default strategy
  gTemperatureSensors*
  // Persist the value for all the members of the group gLivingroomLights every time they change and restore them after a restart
  gLivingroomLights* : everyChange, restoreOnStartup
  //Persist the value of the group itself
  gLivingroomLights : everyUpdate, restoreOnStartup
  //store the value of the temperature every Tuesday at 5PM...So useful...who wouldn't wanna know that?
  mqtt_outside_temperature : everyTuesdayAtFive
  }

As you can imagine, strategies like everyDayAtMidnight  or everyTuesdayAtFive aren't very useful using MapDB. Don't worry, though, in the next post of the series, I will be explaining how to capture historical information and create charts with it.

You may want to also check the openHAB Documentation on Persistence for more details.